[Doc-SIG] Evolution of library documentation

[Ka-Ping Yee]

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
the opposite?

> > 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
> gripe.

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.)

Agreed.

> 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.


-- ?!ng

"Computers are useless.  They can only give you answers."
    -- Pablo Picasso