launchpad-dev team mailing list archive

[Julian Edwards <julian.edwards@xxxxxxxxxxxxx>]

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 
:)