launchpad-dev team mailing list archive

[Huw Wilkins <huw.wilkins@xxxxxxxxxxxxx>]

On 10/07/2011 12:42 PM, Martin Pool wrote:
> On 7 October 2011 12:31, Robert Collins<robertc@xxxxxxxxxxxxxxxxx>  wrote:
> >   - I've flip-flopped over the years pro and con wikis for docs.
> > Currently I think they are great, measured by:
> >   * instant publication
> >   * existing infrastructure
> >   * 0 landing overhead
> >   - I think in-tree docs are essential for projects that ship product
> > to users: our individual reusable code components should have such
> > docs (both README and API, and *perhaps* a manual if appropriate).
> >   - Launchpad itself doesn't ship product to users, its online, and
> > putting our (non-API) docs in tree doesn't help users at all - it
> > forces us to publish them separately, which is more complex and
> > unnecessary.
> >   - Our documentation about using the API should be in-tree, so that
> > they can be tested and shown to work; they should be published with
> > the API (both the json web API and our programmatic API).
> >   - Truely conceptual docs, like the architecture guide, coding
> > standards, tips and tricks - that should be in the wiki
> +1 to all of that.
>
> lp still has some considerable landing overhead, compared to changes
> to the wiki being very quick.
I really agree with this. I would be much less likely to contribute to a 
doc (I would probably never do small edits) if I then had to spend 30 
mins to an hour of my time landing that change.
> 'docs rot' is a constant where ever they are; the main answer to that
> is to edit boldly, either adding answers to new things when they come
> up, or deleting.
I think one of the big things here is that with offline docs it is 
really easy to see what exists and to grep through to make changes. 
Additionally, the web interface gives us clear navigation (mostly by 
exposing everything). I find all those things a lot harder to do with a 
wiki like Moin (at least I'm not aware of any document management views 
that help with that).