It’s Time We Stopped Rewarding Projects with Crappy Documentation | Hacker News Reader

It’s Time We Stopped Rewarding Projects with Crappy Documentation

cforcoding.com

31 pointscletus35 comments

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

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.

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?

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

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

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

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

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

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.

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.

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.

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

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.

> 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

Good clean code is the best documentation.

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.

It's sort of a 'teach a man to fish' problem. If someone is standing on the corner of a hypothetical 14th Street, and if the layout was something like "the Streets run East-West, and the numbers go up as one goes North", it's probably worth their while to explain this. And if the city is designed such that all the avenues are alphabetical from East to West, I'd probably mention this as well.

Personally, I greatly prefer to receive directions that include some redundancy and background information. And yes, every now and then I think "Wow, those were great directions" when someone gives me an explanation that increases my knowledge beyond the narrow scope of my question.

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?

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

But I don't use your software. I use software written to be used. Web.py is written to be used. The developers want people to find it useful. Lighttpd is written to be used. Apache's software is written to be used. Ruby and Python are written to be used. Perl is written to be used. Yes, they may all be fun for the developers, but ultimately, they strive to be useful. I'm sure not every aspect of developing a major open source project like one of these is fun. I don't know anyone who finds debugging fun, for example. It has to be done though if you want to produce something useful (even if only to yourself). Documentation really should be done if you want to produce something useful to someone other than yourself... and even to yourself if there's any chance you'll leave it alone for years and then pick it up again.

You make a good point, however:

1. I have had many people become angry with my stance on documentation for MY projects (written with the above contraints, for fun, for me, if you want to use it: cool not my goal tho). That sort of entitlement ruins it for everyone.

2. It is still done for free, if you don't like the results offer compensation for your choice of improvement. If the work is all volunteer, some stuff that isn't fun won't be done. (debugging is more fun than documenting, since the former is required for something to work right). This is why most non-profits also include someone who is either paid or otherwise rewarded for doing the crap work.

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.

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

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.

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.

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.

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

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

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

agh, get out of my head!

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.

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

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.

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.

Absolutely. I think this is the real answer. Developers need to learn to document and improve their UI skills. To me those are core skills of a developer. We can't expect professionals in those areas to come in and rescue open source.

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.

Reply on news.ycombinator.com