Re: "Section" in *.doc-base file.
On Wed, Aug 15, 2001 at 09:23:28AM +0900, Yoshito Komatsu wrote:
> On Tue, Aug 14, 2001 at 11:59:50PM +0900, Junichi Uekawa wrote:
> > In Tue, 14 Aug 2001 10:24:34 +0200 Michael cum veritate scripsit :
> > > On 14.08.01 at 14:03:47, Yoshito Komatsu wrote:
> > > > Apps/
> > > > Programming
> > > >
> > > > Devel/
> > >
> > > How do I decide which of these two sections a program belongs to?
> >
> >
> > This is too vague. I think we should remove "Devel" if it's possible,
> > or define Devel as to only onclude "standard documentation"
> > like STL documentation, C language reference, and MPI specification.
> >
> > Docs on programming environments should be in Apps/Programming.
>
> I think Apps/Programming is for all applications for programming
> (including IDEs, unix-like tools, and so on),
> Devel/ is for other documents (library references, RFCs,
> HTML references, and so on), they're not applications.
I guess the question to ask is not "can we make a distinction between
Apps/Programming and Devel", but rather "faced with these two choices,
what would most people assume?". One is, after all, putting documents
into categories in order to help folks.
If I am in the middle of coding and want to check out the STL
documents, I am thinking "programming". Ditto if I want to check out
an obscure compiler flag. It will take me a moment's though to make
the distinction between "devel" and "apps/programming". The compiler
documentation is closer (in my mind, at least) to library documentation
than to documentation for other "apps".
One alternative strategy is to use "programming" (or "devel") at the
top level, and split (if necessary) at the second level into, e.g.,
"programming/libraries" and "programming/tools". This captures the
notion that GCC and STL (both "programming" things) are more related
than GCC and LaTeX (both "apps").
Additionally, there can be problems with putting related categories on
different levels: "devel" is top level and "programming" is under
"apps". For one thing, this human tends to scan on the top-level
category first, so I tend to be drawn first to "devel" for programming
stuff. For another, a documentation tool might show only the
top-level categories, and expand the category when selected. In such
a case, there is no way to know about the "programming" hidden under
"apps". Or you might have the opposite problem: consider dhelp. It
appears to ignore the levels completely. Instead of
"apps/programming", the index page for dhelp shows only "programming".
It also shows "devel". Now that is very confusing! When searching
for a document, how is one to choose between "programming" and
"devel"? I know that I seem guess incorrectly at least half the time.
I'll continue my train of thought in a follow-up to your most recent proposal
http://lists.debian.org/debian-devel/2001/debian-devel-200108/msg00975.html.
-Steve
--
by Rocket to the Moon,
by Airplane to the Rocket,
by Taxi to the Airport,
by Frontdoor to the Taxi,
by throwing back the blanket and laying down the legs ...
- They Might Be Giants
Reply to: