WTFM - Write The Freaking Manual

When it comes to open source work, which I mostly do on my own, limited time and don't get paid for, I have a choice. I can spend time writing code or writing documentation. The former I enjoy very much, the latter I don't like at all. Guess which I am going to pick.

The times when I've actually ended up writing some docs, I don't think anyone has ever read them. And writing the docs is just the beginning, they have to be maintained too. Out of date docs are perhaps worse than no docs at all.

I don't read docs either, because they tend to be out of date. Formal specifications are an exception. But when it comes to open source, I just tend to read the source because it's never out of date and tells the whole story. What was obvious to writer of the doc isn't obvious to me and vice versa.

The first person who comes to me asking for documentation to my projects volunteers to write them, like it or not.

And please, run your source through a tool like doxygen for me to get a better understanding of how your software is built and designed. I've been advising a startup that is facing issues with documentation not being available for the platform they chose to use. The platform looks good, and the code is fairly readable, but there is no documentation. To complicate things, the platform is under active development and things change weekly (if not daily). The solution? The startup is looking to have their application written in another platform. All we need is for you to explain how stuff works in a language that even a grilled cheese sandwich will understand.

Any pointers on how to make it easier to wtfm? If anyone out there actually enjoys writing documentation I'd be willing to pay for some help and guidance on a rather large commercial open source project that is in need of some tlc regarding documentation

There are actually many open-source projects that have excellent documentation and there are many that don't have documentation at all. I think there's actually a shortage of projects with simply adequate documentation.

Many open-source projects also allow you to contribute to the documentation, so I don't think you should criticize projects you're actually using but rather that you should help maintain the documentation (even if it's just bug reports).

If you have an open-source project with very few users, you'll often find that you can't get traction simply because when people can't figure out how to use your software, they'll go elsewhere. Want fame and (maybe) fortune? Make your project useable.

I've wasted hundreds of hours dealing with piss-poor or no documentation, reading/debugging code, searching sites and forums just to find the magical combo of steps that get a application to build correctly or an LED to blink.

I don't have unlimited time to figure out your code, API and lack of documents. I would rather deal with OSS or commercial software that respects me.