On Tuesday 04 October 2011 17:38:01 Francis J. Lacoste 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 think we are all pulling in different directions and nobody is steering the rudderless documentation ship. There are now three places to maintain documentation: the dev wiki, RTD (Sphnix) and doctests. I'd like to start a rational discussion on how we should be managing this sort of thing because quite frankly it's getting annoying not knowing where to look, even if I already know something is on the wiki. Stub's "wikis are where documentation goes to die" is a bit of an emotional comment but reminds us that documentation is able to become out of date very, very quickly unless it's maintained. Doctests, while able to help a little here, are not a panacea. So, I differ from him in that I believe this applies no matter where documentation lives. I do like the general idea of keeping documentation in our tree and generating HTML from it. It's partly why I started the /LongPoll wiki pages in rst format so that we can drop the same raw text anywhere. Doing this seems to have several advantages: * it's more easily searchable * it's available offline * it's easier to update the documentation along with the code Perhaps the dev wiki should only contain information that is more likely to remain static, such as "getting the code", "debugging tips" etc. I am happy to collate opinions on this and drive it forwards. _______________________________________________ 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
