launchpad-dev team mailing list archive

[Martin Pool <mbp@xxxxxxxxxxxxx>]

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.

'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.

m