launchpad-dev team mailing list archive

[Julian Edwards <julian.edwards@xxxxxxxxxxxxx>]

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.