
It’s Time We Stopped Rewarding Projects with Crappy Documentation - cletus
http://www.cforcoding.com/2009/08/its-time-we-stopped-rewarding-projects.html
======
tjic
When people say "we need to all stop doing X and do Y", I am tempted to
reorder the statement into a question:

Q: _WHY_ do we reward projects with crappy documentation?

Heinlein had a statement: "any time people ask a question that starts with
'why', the answer is usually 'money'".

For values of "money" == "value", this is the answer to why we use projects
with crappy docs.

If using a good codebase with crappy docs delivers more bang for the buck than
using a crappier codebase, then it is in everyone's best interest to use that
great codebase.

Instead of issuing blanket cries for unified action, a better approach is to
figure out

(a) what the actual issue is, and then

(b) [ if I may allow my inner capitalist to vent ] come up with a way to
increase value for everyone by fixing the issue in return for some mutually
beneficial trade.

Part of the Free Software idea is that free software generates follow on work.
Perhaps some of that follow on work should be "the un fun task of generating
docs".

~~~
sophacles
In this case, I'm fairly certain your last sentence gets to the heart of the
issue. The biggest motive of most people writing OSS stuff is: Fun.
Documenting is un-fun. Since there is 0 obligation on the author's part and
any benefit gained by others is a side-effect, documents won't get written,
particularly to appease people who come in an demand better docs without
offering any compensation.

------
URSpider94
The time-tested market solution to this problem seems to be that a bunch of
1337 hackers create a solid open-source package that you can download for
free, then an author comes along, writes a thorough set of documentation for
it, and publishes it through O'Reilly for $30 per copy.

Why do people put up with this model? Maybe because nobody expects any better,
maybe because $30 is short money for well-written documentation. As a
rhetorical question, have you ever worked on a project (open-source or closed,
internal or external) where documentation writing was anything other than an
after-thought?

~~~
timwiseman
* maybe because $30 is short money for well-written documentation.*

For sufficiently complex and powerful software and sufficiently well written
documentation, it is.

------
nkurz
> Otherwise I’m just not interested anymore.

I'm afraid your article rubs me the wrong way. Could you explain further why
an independent developer (who has written code in their own time to satisfy
their own need) has _any_ obligation to satisfy your desire for better
documentation? I can certainly understand why one wouldn't choose to use
undocumented code, and why one wouldn't recommend it to others, but I don't
understand the sense of entitlement.

Further, what greater obligation does the original author have that you as a
user of the code do not? Why should the author be expected to sit down and
write documentation intended solely for the use of others, whereas you, now
capable of doing the same, do not? Your 'duty of care' argument falls short
for me, and instead I see a favor not being returned.

I don't mean to be too negative (your writing style itself is great, for
example) but I really don't understand the underlying sentiment.

~~~
Semiapies
You might as well ask why an independent developer has any obligation to
release code that actually works most of the time.

No, in the broadest sense, there's no moral or legal obligation. However, in
the social sense of interacting with people that you're offering software to,
you're not doing a favor to anyone by releasing crappy code or putting up
lousy documentation.

You may be confused by the level of the argument - it's not at the level of
"must", but "should".

------
jgrahamc
That reminds me of a three year old blog posting of mine:
[http://www.jgc.org/blog/2006/07/open-source-elephant-in-
room...](http://www.jgc.org/blog/2006/07/open-source-elephant-in-room-
source.html)

~~~
DanielStraight
Excellent article. I literally laughed out loud when I read the 59% of
projects had negative scores.

Another plus for this article (that you probably didn't have in mind when
writing it) is that it gives readers an idea of what open source projects are
good choices for practicing reading code. So many people recommend reading
code, but no one ever recommends what to read. Kudos for giving me a starting
place.

------
ivanyv
I agree with most of his points, but let's be honest people, writing good
documentation is no easy task. And not many programmers are good communicators
either.

~~~
baha_man
Writing good code is both difficult and all about communication. If you can
write good code, you're probably capable of writing good documentation (low
level technical documentation in your native language, at any rate) if you
really want to.

~~~
mechanical_fish
By "no easy task" he doesn't mean it's some kind of intractable problem.
(Though it _is_ much harder for some than others.) The problem is that it
takes non-negotiable amounts of time. Writing is _work_.

Even if you're one of those rare people who can just sit down and type press-
ready copy ( _cough_ Isaac Asimov _cough_ ) it takes time to physically _type_
it all.

------
blhack
Writing documentation is NOT fun.

Writing really cool code is...

What you're asking is that people turn projects that are "fun" into projects
that are "work" and still do it for free?

Really? Because I'm perfectly content using software that works, works really
well (better than the costly alternative in some cases), and is 100% free. I'm
totally fine with having to find some of the devs on IRC or a mailing list
instead of having to look through some docs.

Yeah, documentation is really nice, but suggsting that we stop using projects
that have poor documentation is a bit silly.

------
conanite
I would bet that any popular open-source project became popular _before_ it
had any decent documentation (assuming it has any now). The biggest block, for
me, when writing documentation, is that I'm writing for a mystery audience, I
don't know what their problems will be, or what questions they will ask. But
once your project is used widely, documentation is just a matter of
refactoring the mailing lists. And that's an itch some developers are willing
to scratch - nobody wants to answer the same questions over and over.

------
dasil003
Would you rather have a good library with no documentation or a bad library
with great documentation? I don't say that because I disagree with the OA in
any way, but just to point out why people "reward" projects with crappy
documentation, and why it might be a hard problem to resolve by peer pressure.

~~~
Semiapies
I'll bite...When's the last time you've seen crappy open source code with
"great documentation"?

------
dan_the_welder
So what's it going to take to draw UI and documentation people to open source?

~~~
michael_dorfman
Money?

Seriously, I don't know too many people whose idea of "scratching an itch" is
writing documentation. There aren't a lot of documentation-hobbyists out
there, as far as I know...

~~~
robotrout
I've found the feeding infants a mixture of milk mixed with 25% pulverized IRS
forms and 10% pulverized army field manuals, results in a 65% chance that by
age 8, they will be obsessed with writing documentation.

By next year, we'll have an army of 1,000,000 tech writers ready to serve the
emperor and rebuild the empire, errr, or at least document it's rebuilding.

~~~
billswift
I'm curious, is your user name supposed to be Robo-Trout or Robot-Rout?

