It’s Time We Stopped Rewarding Projects with Crappy Documentation

http://www.cforcoding.com/2009/08/its-time-we-stopped-rewarding-projects.html

by cletus • 17 years ago

31 35 17 years ago

jgrahamc• 17 years ago

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

DanielStraight4• 17 years ago

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.

ivanyv2• 17 years ago

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• 17 years ago

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.

ivanyv2• 17 years ago

I kind of disagree. While I agree with your first statement somewhat, I know many programmers who can express themselves pretty well in their language of choice, but when it comes to human communication, well... ;-)

mechanical_fish• 17 years ago

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.

tjic2• 17 years ago

> If you can write good code, you're probably capable of writing good documentation

Indeed, but is that the best use of time for someone who can write good code?

http://en.wikipedia.org/wiki/Ricardo%27s_law

LostInTheWoods• 17 years ago

Good clean code is the best documentation.

DanielStraight4• 17 years ago

It really isn't. Just like a well-designed city is not the best map or the best directions. If you asked someone for directions and they started explaining the entire layout of the city instead of just telling you where to go, would you say, "Thanks man, those were the best directions I've ever been given"? No, you'd probably ask someone else.

DanielStraight4• 17 years ago

While it may be true that writing good documentation is not easy, writing bad documentation IS easy, so why do so many coders not even do that?

sophacles3• 17 years ago

I write open source software for fun. No other reason. Your ability to use my software for stuff is a side benefit for you of this. Writing documentation is not fun. I don't want to fill my fun time with not fun activity. I will however take money for writing documentation (quality not guaranteed).

Semiapies3• 17 years ago

Let's be blunt: Sturgeon's Law applies. Many coders are lazy and half-assed. They take little pride in their work.

This is why you see so many little aborted projects where someone lost interest after the first weekend of work. This is why you see defensive coders complaining about how people expect their "active" project to ever update again. For many of them, there's not much interest in offering a useful tool or collaborating to create better software; they just want the egoboo of saying they made a "project" out of some slapped-together code that never really needed to be in a public repository.

billswift2• 17 years ago

Even bad writing isn't really very easy. And bad documentation can make the situation worse. Why would anyone want to do that?

dan_the_welder• 17 years ago

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

michael_dorfman• 17 years ago

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

dasil0034• 17 years ago

agh, get out of my head!

robotrout• 17 years ago

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.

dasil0034• 17 years ago

I think a paycheck is the only way for most projects.

Open source developers are scratching an itch. What itch would a UI or documentation person be scratching? The project would only be relevant if it's a user-facing app that they themselves use.

ubernostrum• 17 years ago

Well, you can also encourage contributors to document their work. With Django, for example, our policy is that a submitted patch will not be committed unless it includes both unit tests and documentation in addition to the code.

This means it can take longer for a patch to be accepted, but it also means that the documentation stays up-to-date.

anigbrowl• 17 years ago

Money. Not a ton, but it's a very time-consuming job.

I do like writing documentation, and I'm pretty good at it. Unfortunately it's a thankless task, and criticizing or feeding back to developers about shortcomings often engenders a frosty reply, so I rarely do it any more. Add in the fact that for simpler software, good UI design often makes documentation redundant, are you have to deal with the fact that the things most in need of good documentation fall into two classes:

a) domains of expertise where the documentation needs to be as much an introduction to the task for which the software is used as how to use it. Example: Adobe sells a great, great piece of audio editing software called Audition. It has been my favorite for over a decade. The manual is...well, generic. Before they bought the product, it was called CoolEdit, and it had one of the best manuals I've ever read: written by the main author of the project, it was as much an introduction to signal processing and audio engineering as a guide to using the program, since the utility of many fine features is not apparent to the novice user. Inexplicably when Adobe took over the project they ditched this - perhaps preferring to rely on third party publishers or their own publishing imprint (which is quite good). Some of the best documentation, like the above, gives the sense of having been written before the code, rather than afterwards when the programmer is burnt out.

b) legacy systems which may completely suck but which we are stuck with. Unfortunately, project managers tend not to look kindly on documentation that starts by acknowledging the software in question is poorly designed, confusing, or contains bugs which may never be fixed. They want documentation that tells yo how things are supposed to work, not documentation that goes into detail about what happens when it fails and how to deal with it (although this is the time when the end user is most in need of quality information).

There's one other problem, that of social exclusion. It's assumed by certain kinds of programmers and administrators that the code or tools must be accepted much as they are, and if one finds the system opaque or perplexing that that is part of the price one pays to develop expertise in it.

Many years ago, when I first installed Linux, I ended up at a shell prompt armed only with the knowledge of cd and ls. Typing 'help' yielded only a polite error. It took me quite a while to discover the 'man' (manual) command, and when I did I was less than impressed with much of the documentation. As mentioned above, many man pages devote no time whatsoever to explaining why you might want to use something. This is a kind of an artificial example, but one that encapsulates the seemingly arbitrary and unfriendly experience of computing for many people.

Reference materials usually do not perform very well as tutorial materials, and yet they are likely to be the first thing the typical user encounters. I made fun of Microsoft's Clippy character along with everyone else, but for the general user who just wanted to use the computer rather than understand it, it was actually a godsend.

dasil0034• 17 years ago

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.

Semiapies3• 17 years ago

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

URSpider94• 17 years ago

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• 17 years ago

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

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

tjic2• 17 years ago

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

sophacles3• 17 years ago

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.

nkurz2• 17 years ago

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

Semiapies3• 17 years ago

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

blhack• 17 years ago

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• 17 years ago

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.

It’s Time We Stopped Rewarding Projects with Crappy Documentation

Related Stories