On Wed, Oct 5, 2011 at 4:38 AM, Francis J. Lacoste <francis.laco...@canonical.com> 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 <stu...@stuartbishop.net> http://www.stuartbishop.net/ _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : launchpad-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
