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 _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : launchpad-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
