Hi Ian
On 24 Oct 2002, Ian Bicking wrote:
> Anyway, I've been writing lots of documentation lately, and I've been
> using reStructuredText (http://docutils.sourceforge.net/rst.html). It's
> worked pretty well for me -- the output looks decent, but more
> importantly it's comfortable to write. Keeping the documentation
> up-to-date is the most essential part.
>
> In some way we should also split the documentation up for the different
> parts -- Application, Adapters, Page, ... maybe all in the same file, or
> a couple files... I'm not sure. Anyway, we could then really try to
> keep it up to date with any changes to the code.
>
> What do people think about reST? Docbook is spiffier, but I dread
> actually writing it, and we're content-poor, not formating-poor.
I looked at reStructuredText some time ago - and liked it. The format
is not _very_ readable in its "source" form, but it's a very good
compromise between maintainabilty and readabilty, I think. If the
format is just the source for HTML docs that most people would read
that would be ok.
> Another option is utilizing doc strings for more. I'm not really sold
> on it, but if someone feels more comfortable about generating real
> documentation that way it might be a good idea. But generated
> documentation like that just never looks quite right to me. It lacks
> useful structure, it's bound to methods, and the documentation seems to
> put trivial methods on par with important methods. But I'll look at
> docutils more closely... though it's at an early stage. But I would be
> open to tweaking docutils to make it work...
>
> Actually, I guess my real issue is that inline documentation doesn't
> distinguish between user interfaces and internal interfaces --
> particularly when those internal interfaces are not entirely internal,
> like methods that you may wish to override in a subclass, but which you
> wouldn't call directly.
I share your objections on doing all documentation via docstrings. I
also sometimes find myself struggling on whether I should rely only on
docstrings (because it's convenient and doesn't afford to write some
things twice) or not (because of the reasons you mentioned). In my
opinion, it's better to have extra documentation besides the
docstrings and as a user of Webware I would prefer to have the extra
documentation. Additionally, even (potential) developers would be
better off with starting with overviews and _then_ reading source
code/docstrings. Then, attracting more users which eventually become
contributors might make the further development of Webware easier.
> And when you look at classes like HTTPServlet and Page, it only confuses
> people to present all that, when a document on servlets (in all forms)
> would be much more helpful.
Agreed.
Stefan
|