launchpad-dev team mailing list archive

[John Arbash Meinel <john@xxxxxxxxxxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 10/7/2011 3:42 AM, Martin Pool wrote:
> On 7 October 2011 12:31, Robert Collins <robertc@xxxxxxxxxxxxxxxxx>
> wrote:
>> - 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.
...

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

The only thing I want to point out is that if docs are in-tree, you
can do "grep -rnI OldAPI" to update the callers of your api, and to
notice that there is some documentation about the old api that should
be updated.

It is quite a bit harder to do that if the docs are in the wiki, but
that might fall under:

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

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk6OqBwACgkQJdeBCYSNAANxnACfT/41RA+YJp8HscPf9l85Ha9l
qLcAnjWwF4zmll2IcUn9Pfrmexl2jxXG
=mIog
-----END PGP SIGNATURE-----