-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 10/7/2011 3:42 AM, Martin Pool wrote: > On 7 October 2011 12:31, Robert Collins <robe...@robertcollins.net> > 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----- _______________________________________________ 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
