launchpad-dev team mailing list archive

[Robert Collins <robertc@xxxxxxxxxxxxxxxxx>]

FWIW, here are my thoughts:
 - the dev wiki is already locked down to just trusted folk; we don't
spend -any- time verifying changes from randoms there, and folk in the
team that are interested in review can do so easily
 - I dispute our need for extreme accuracy; if we /needed/ that we'd
be sunk already. Aiming for extreme accuracy requires tradeoffs that
will cost us, and I've /never/ seen - even in a fully tested
documentation setting - docs stay totally up to date. Trivial example:
an API change to make a newer API exist, which should be preferred by
everyone. Docs won't fail (old API is still valid); care and
significant attention to detail are the ingredients to keep on top of
that - and that costs, which is the tradeoff I'm talking about.

 - 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

-Rob