On Wednesday 05 October 2011 10:34:24 Julian Edwards wrote: > 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.
I'm pretty sure you guys are more opinionated than this. C'mon, let us have it :) _______________________________________________ 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
