Bounties for docs?

Bounties for docs?

Summary: I've been meaning to mention Google's "Summer of Code" for some time. Google is sponsoring work on open source projects by paying students a $4,500 stipend to dig in and work on projects.

TOPICS: Open Source

I've been meaning to mention Google's "Summer of Code" for some time. Google is sponsoring work on open source projects by paying students a $4,500 stipend to dig in and work on projects. Google isn't alone here: A number of open source projects have "bounty" programs to pay for features that are needed or wanted. I think the bounties programs that some other open source projects have are also great ideas. But it seems that a crucial area is often overlooked: Documentation. Why isn't documentation a higher priority for the "bounty" programs?

It's been mentioned before, but documentation is still one of the weakest parts of many open source projects. There are exceptions: I think Apache has excellent documentation, for example. But even corporate-sponsored projects like MySQL -- which has excellent online documentation overall -- lack docs in some crucial areas. Try finding good documenation on compiling and using MySQL with SSL, for example. MySQL doesn't provide binaries with SSL compiled in, (due to licensing issues) and the docs to do so are meager at best.

Before anyone dares to suggest that proprietary software is better in this regard, don't. I have worked with plenty of proprietary apps that have abysmal documentation -- which is doubly annoying, since you're paying for the privilege of using poorly-documented software. Frankly, it's an industry-wide problem -- open source, proprietary software, and internal projects for organizations that may not even carry a license, tend to suffer from poor (or non-existent) documentation.

Admins and programmers typically don't like to write documentation and tend to produce sub-par documentation (or, even if they do enjoy it and produce excellent docs, lack the time to do so) and most companies seem to do documentation as an afterthought. It doesn't help to have great software if the documentation isn't sufficient for users to become productive with it. It's great to see Google, et al, spending money to help move the software forward -- but I hope that open source companies will start taking documentation projects under their wing as well, so that more users can actually benefit from open source projects.

Topic: Open Source

Kick off your day with ZDNet's daily email newsletter. It's the freshest tech news and opinion, served hot. Get it.


Log in or register to join the discussion
  • Part of the solution

    A friend recently tried to volunteer to do some documentation work for an F/OSS project. She is a professional tech writer who uses the software and knows what the documentation isn't.

    She gave up.

    The problem was that she asked for the same things she would have expected on any other project: the specifications. There weren't any. So she volunteered to write specs, based on the same input she needs in a commercial project: developer input. Couldn't get any. The usual response was, "read the code."

    She did what she could to reverse-engineer the software from the UI, and when she had done what she could asked for review and input. Responses were not, to be kind, positive. Nor helpful.

    So she gave up.

    Yes, documentation is a problem. It's also not going to get better until projects get past believing that code (and coders) are all that matters. Some have. Some may never.
    Yagotta B. Kidding
    • open source code

      I've looked at open source code and it isnt anything like what pro open source advocates claim (its designed with security in mind, its better written).
      My opinion open source code is like open source documentation.
  • Been there done that!

    When I was going through my two years for my AAS in CIS degree, the instructors emphasized documentation, both flowcharting (be it ANSI, Nassi-Schinderman, TOE) and user documentation. But unfortunately those are monetary resources that can be better spent else were. That is why when it comes to user manuals, I always bought books from what I call second source books (other then the software manufactures instruction manuals, usually these manuals are poorly written or so caught up in technicalese as to be of little or no use to the end user, cryptic error codes or messages are also an issue). When I tutored other students I would always stress how important documentation is. But corporations will not listen, it is cheaper to pay for consultants. I myself do double duty when I write code, within the code, comment liberally. Create technical manuals and create end user manuals without the technical jargon.