[wp-hackers] Inline Documentation Effort was a Failure

[Peter Westwood]

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

Ryan Boren wrote:
| On Wed, May 21, 2008 at 9:21 PM, DD32 <wordpress at dd32.id.au> wrote:
|> One word, Lazy.   (For anyone who reads this paragraph, and doesnt
bother to
|> read the rest, Please read Paragraph 6 before flaming)
|> Developers are lazy people in general, If something does not give them a
|> benefit in the imminent future, chances are, its not likely to be taken.
|
| As described famously by Larry Wall:
|
| http://c2.com/cgi/wiki?LazinessImpatienceHubris
|
|> Jacob, The documentation wasnt a waste of your time at all, Thank you for
|> all the docs, Really, Thank you, It'll be a shame if its the only real
|> documentation in the code, But i'm sure many people have allready been
|> helped by it.
Jacob++

The documentation was worth writing.  It makes things like this [1] much
more useful.

|> As to writing more, If you do, Great for you :), If you dont, Then i dont
|> blame you. In order to continue you need support, And if theres no
support
|> there from major devs, then you dont get very far.
|
| I support inline docs by committing others patches and trying to
| document new public API as it goes in.  Those who want inline docs
| need to step up; I have enough tedious chores on my plate. :-)
|

We do need to promote and request the submission of inline docs with new
code though.  The best time to write the documentation is when you are
writing the code :-)

Writing documentation along with Code Review are good ways to validate
the code.

westi

[1] http://sandbox.ftwr.co.uk/wp/nav.html?index.html
- --
Peter Westwood
http://blog.ftwr.co.uk | http://westi.wordpress.com
~ C53C F8FC 8796 8508 88D6 C950 54F4 5DCD A834 01C5
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFINagjVPRdzag0AcURAn0rAJ99KXW/bztjAdlDoMTg0XRURoez/gCdFSRW
irTj5R2a9zrrI5ws+aPMajQ=
=7pS4
-----END PGP SIGNATURE-----