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
signature.asc
Description: PGP signature
_______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
