[Doc-SIG] Evolution of library documentation
Mon, 12 Mar 2001 03:30:42 -0800 (PST)
On Mon, 12 Mar 2001, Tony J Ibbs (Tibs) wrote:
> Hmm. I've had this argument before.
Okay. Well, i think it's good to have this particular debate. It's
worth discussing, so please bear with me as i argue it out with you.
> Not *necessarily* a bad goal (although I would point out it's
> *significantly* easier to "have TeX" than, for instance, to "have CVS",
This really surprised me. CVS is installed by default, i believe,
on all modern Linux distributions, and i have yet to install TeX,
which is much bigger and more complex. How is it that you perceive
> > This would address the duplication problem and
> > also keep all of a module's documentation in one place together with
> > the module.
> Now, if you said "package" I'd be happy, but since it's "module", I'll
But the library reference manual is arranged by module, and there
is a chapter of documentation on each individual module. It also
makes sense since the modules are the organizational units that you
import and name in your code.
> Aagh! No, sorry, my problem wouldn't be with paging (although that *is*
> a problem - and why is the end of the file so different than the
> front? - I page from both ends, depending on context!).
I do think the inconvenience is mitigated by putting the docs at the
end -- but i acknowledge that having bigger files is a concern.
I don't see this as a 100% win myself -- it just seems that keeping
the code and docs in the same file has advantages large enough to
outweigh the inconvenience.
> Tutorial, reference and other "grander scope" documentation relates to
> the source code as a whole.
Can you delineate clearly what you consider "grander scope" documentation
as opposed to "point" documenation on a particular module? I'd like to
better understand what you mean by "different" in the sense of different
enough that something should be in a separate file.
> (That's an important point - docstrings must be suitable
> for browsing with an IDE.)
> Also, *because* one might have more than one sort of "grander scope"
> documentation for a module/package, you will have to consider
> *supporting* more than one.
Could you give an example?
> And I for one reckon that we probably don't have a
> Guido-of-the-markup-languages hanging around on our list (it's
> statistically unlikely).
By Guido-of-the-markup-languages did you mean "benevolent dictator" or
"good designer" or "long-term keeper of the faith" or something else?
> 1. People *will not* markup heavily (we cannot make them do it, they
> will not do it), so we need to specify a markup that doesn't have a high
> learning curve, and that doesn't have many *ways* of marking up
> > markup tags that are used there. Here follows my list; i
> > have attempted to categorize the purpose of the tags by hand.
> At which point I think I rest my case - there are *lots* of these.
Although it may seem surprising, i don't immediately conclude that
there are so many tags that we can't possibly design a reasonably
useful markup syntax. Many of the tags are redundant or produce
shades of meaning finer than i consider really necessary.
I'm not claiming it's possible until i really give it a try, but
i do think it's worth a serious attempt.
"Computers are useless. They can only give you answers."
-- Pablo Picasso