Open Source Manual Writers

Open source and I did not start out on the right foot.

Open source is software that is developed globally via the Internet by anyone who wants to contribute through freely available source code. Developers can contribute by fixing bugs, adding features, or extending functionality with the understanding that the resulting software will be free for anyone to use and modify, if they want.

My first experience with open source was a project that required we use ChiliSoft, the open source version of Microsoft’s scripting language for building dynamic web sites.

It was a nightmare because there was no documentation you could consult when you ran into a problem. If you encountered an error or bug, you had to just sorta figure it out yourself. Microsoft, by comparison, has extensive documentation for ASP.  If you encounter a problem, there’s a place for you to find a definitive answer to solve your problem.

While I’ve warmed considerably to open source solutions, the lack of documentation is still a major drawback if you decide to use open source. If there is a user manual included, it’s most likely bare bones.

What generally passes for documentation for a given open source project is an online discussion board where you can find threads that typically begin with "Has anyone had this problem…?" followed by a discussion of the board members trying to diagnose the problem and sometimes arriving at a solution, sometimes not.

The open source movement has a lot going for it: Full featured, sophisticated, extensible, and stable software solutions that, by the way, are free. But the major flaw is that because of the lack of adequate documentation, you end up spending a lot more labor diagnosing and solving problems than you would with proprietary software.

What the open source movement desperately needs are open source writers. Not coders. Coders are usually not experts at the written word and, because they’re technically proficient, they often take for granted that the people reading the manuals will have the same technical acumen as themselves. When coders write manuals, the manuals are often unreadable.

What the open source movement needs are people who can write software manuals in lay language. You occasionally see a wiki  that’s been set up to serve as the documentation for an open source project.

That’s a great idea, but the wiki’s I’ve seen used for this purpose have been hit and miss, often incomplete and inadequate. It seems to me that there should be some agreed-upon standard for open source documentation that people working on open source projects can come to expect.

Perhaps the solution is to include within the message board software prompts to encourage users to contribute their solutions to the wiki manual.

I just don’t think that open source software can really gain mainstream adoption until this particular problem is solved.