launchpad-dev team mailing list archive

[Barry Warsaw <barry@xxxxxxxxxxxxx>]

On Feb 11, 2010, at 09:37 AM, Bjorn Tillenius wrote:

>My basic ideas so far is to make the doctests into actual documentation. For
>each major part of Launchpad, there should be a doctest describing the
>part. That doctest can link to other doctests which describes the part in
>more detail, or describes sub-parts.

This is a really excellent idea.  My suggestion would be to try to integrate
Sphinx to generate html (and other formats) from our doctests.  In theory that
shouldn't be too hard to do given our buildout infrastructure.  Once we have
reliable Sphinx output (regardless of quality), let's publish it to
docs.launchpad.net and update it every day.  We probably want to publish the
devel and db-devel branches.

I think once we see the pretty output, we'll be more motivated to
opportunistically improve it as we go.  That can include cleaning up what we
already have, writing good new documentation, and moving some stuff to Python
tests.

IME we'll need some overview documentation to pull it all together and give a
consistent high-level view of the system.  The side benefit to all this is
that it will be easier for new developers to dive in.

>That said, documentation can actually be useful for the one writing it.
>This should not be under-estimated.  Explaining how things work, and
>most importantly explaining why things work the way they do, forces you
>to think about how easy things are to understand. If you have trouble
>explaining it, maybe your design is not so good. I know that I have
>realised this a few times, and I'm sure others would as well, if they
>made the effort.

I wholeheartedly agree.  In fact, sometimes it's best to write the
documentation first.  The nice thing is that with TDD and doctests, you're
writing the tests first at the same time. :)

-Barry

Attachment: signature.asc
Description: PGP signature