On Tue, Aug 5, 2008 at 1:07 PM, ara.t.howard <ara.t.howard / gmail.com> wrote:
>
> On Aug 5, 2008, at 9:46 AM, Gregory Brown wrote:
>
>> Nevertheless, that article is utterly devoid of typical _why-isms, it
>> just demonstrates good technical writing.  This is a skill *all*
>> programmers should have, and it is worth brushing up on as needed.  It
>> sort of goes with the territory, most software is only as good as its
>> documentation to all but the most inner circles of the technorati.
>
> i humbly disagree with this.  unpack ruby 1.6.8 and look at the docs.  matz
> isn't a great writer - at least he doesn't spend his time doing great
> writing.  i don't think it detracts one bit from the ruby language.  it's
> *ok* to be good at one thing and let others be good at other things - it's
> the beauty if open source to a certain degree that we can all row together
> to get the project done, docs included.

Fair enough, I definitely didn't mean to overgeneralize.  But I still
stand by the point that programmers *should* have a decent technical
writing skills.  You're absolutely right that when software is
interesting enough, people will contribute documentation.  However,
the farther away from the author of the software you go, the more
difficult it is for someone to write about the topic.  I'm not talking
about tutorials and walk-throughs here, but API documentation.  Eric
Hodel kicks ass for a reason, and that's because he's willing to read
code that he didn't write and document it so others don't have to.
This is something we can appreciate, but not something that should be
expected.  (Again, I use 'should' in the sense of 'would be best', not
in the sense of 'absolutely must')

> i don't think we disagree on this point - rather i think that it's important
> to distinguish between 'libraries' and 'applications' without lumping both
> into the category of 'software'.  in other words to recognize that
> documentation needs are different for different projects.  this is part of
> what makes a one-shoe-fits-all approach hard i think.  it's also why the
> documentation needs of a rails plugin are quite different for a developer
> installing the the plugin vs a graphic designer doing the same.  it's
> unrealistic to expect the plugin developer to cater to both.

This is a good point.  I definitely overgeneralized by lumping
everything into 'software'.  I'm talking about the things that
actually *do* need documentation, such as complicated libraries or
things at that level of complexity.

> ps. also worth noting (not to you greg), but for posterity, is that this
> thread will consume more energy and words than contributing documentation to
> one or two medium sized ruby projects currently just sitting there in svn or
> git in all there undocumented glory

Or continuing to document Ruby itself, as much of the standard library
still leaves something to be desired for.  (Despite the hard work of
those who've made great progress on this over the last couple years)

-greg

-- 
Killer Ruby PDF Generation named after a magnificent sea creature:
http://github.com/sandal/prawn | Non-tech stuff at:
http://metametta.blogspot.com