5 ms·
It’s Time We Stopped Rewarding Projects with Crappy Documentation
- jgrahamc 17y agoThat reminds me of a three year old blog posting of mine: http://www.jgc.org/blog/2006/07/open-source-elephant-in-room-source.html http://www.jgc.org/blog/2006/07/open-source-elephant-in-room...
- DanielStraight 17y agoExcellent 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 17y agoI 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 17y agoWriting 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.
- ivanyv 17y agoI 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 17y agoBy "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.
- tjic 17y 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 http://en.wikipedia.org/wiki/Ricardo%27s_law
- LostInTheWoods 17y agoGood clean code is the best documentation.
- DanielStraight 17y agoIt 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.
- nkurz 17y agoIt'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.
- DanielStraight 17y agoWhile 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?
- sophacles 17y agoI 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).
- DanielStraight 17y agoBut 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.
- sophacles 17y agoYou 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.
- dan_the_welder 17y agoSo what's it going to take to draw UI and documentation people to open source?
- michael_dorfman 17y agoMoney? 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...
- dasil003 17y agoagh, get out of my head!
- robotrout 17y agoI'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 17y agoI'm curious, is your user name supposed to be Robo-Trout or Robot-Rout?
- dasil003 17y agoI 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 17y agoWell, 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.
- dasil003 17y agoWould 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 17y agoI'll bite...When's the last time you've seen crappy open source code with "great documentation"?
- URSpider94 17y agoThe 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 17y ago* maybe because $30 is short money for well-written documentation.* For sufficiently complex and powerful software and sufficiently well written documentation, it is.
- tjic 17y agoWhen 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 17y agoIn 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.
- nkurz 17y 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.
- Semiapies 17y agoYou 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 17y agoWriting 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 17y agoI 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.