launchpad-dev team mailing list archive

[Stuart Bishop <stuart.bishop@xxxxxxxxxxxxx>]

On Wed, Oct 5, 2011 at 4:38 AM, Francis J. Lacoste
<francis.lacoste@xxxxxxxxxxxxx> wrote:
> Hi there,
>
> The Red squad is progressing rapidly on the productionization of the
> txlongpoll infrastructure. As part of that, they are documenting this
> system (yeah!)
>
>  https://dev.launchpad.net/LongPoll
>
> Seeing that document though, it begs the question if the wiki is where
> that documentation should be authored and maintained.
>
> The alternative would be to maintain-it as sphinx documentation in the
> tree. We have an-up-to-date rendering of this at
> http://launchpad.readthedocs.org/en/latest/
>
> What do you guys think?

I still believe wikis are where documentation goes to die. It will
take a matter of weeks before it is out of date and pointless. We
actively maintain very few wiki pages and the rest are forgotten about
and waste.

For technical documentation like this if it is in some sort of
traditional format like wiki, I think you either need to schedule the
documentation to be revised in a few months. Its doable but I don't
think it scales. When Launchpad grows wikis, I'll be pushing for
metadata on each page for who is assigned to maintain it and a
scheduled revision date and maybe we will end up with a wikis that are
useful for reading about was *is* rather than what *was* or what *was
proposed*.

I prefer documentation that is run as tests, with enough real tests
that force the document to be revised as the codebase is refactored.
And no, not the 'our doctests are horrible because they do too much so
all doctests are evil' type thing, but real documentation that reads
like documentation, with all uninteresting boilerplate and imports and
setup and stuff marked up to be omitted from the docs and the bulk of
the tests living in the main test suite. Reviews would need to review
it as documentation to avoid creep in the tests, ideally it being
easier to add stuff to the main tests rather than shoehorn it into the
documentation.


-- 
Stuart Bishop <stuart@xxxxxxxxxxxxxxxx>
http://www.stuartbishop.net/