How Documentation Should Be

In the last few months, I've been writing documentation for Ractive - a lesser-known but highly flexible UI framework. It's my go-to framework when doing personal projects or when I just want to make things work without futzing with tooling and all that jazz. But while the framework itself is pretty powerful, it has a weakness: It's documentation is a bit behind. So I've been fixing that and learned a few things along the way.

It should be complete

If there's one thing that's problematic in the world of open-source, it's the lack of or the incompleteness of documentation. And often times, developers hide this problem by fronting it with hype, public relations, developer chatrooms, tracked issues and stuff. All of that effort could be avoided if documentation was simply complete.

It should be concise

I'm a regular at Stack Overflow. One pattern I notice is that there are questions whose answers are simply links to the technology's documentation. The problem is usually because the documentation is poor. It's driving away users away when the answer is already there. Documentation shouldn't be like that. It should be straight to the point, giving what the user needs immediately. In and out in a snap.

It should be in one place

As a Drupal developer, I very well know that Drupal is horrible when it comes to documentation. Because of that, developers resort to making external forms of documentation, such as tutorials and webcasts, which easily become invalid over time and are polluting search engines. People should improve the canonical documentation and avoid off-shoot documentation. If writing external content, it should link to the canonical reference.

It should be easy to contribute to

One of the things that's easily overlooked when building documentation: ease of contribution. Documentation is unnecessarily made difficult because of the tools and/or procedures surrounding it. If I just need to correct just one sentence of the documentation, I shouldn't have to deal with build tooling, deployment, and all that stuff. I should only be editing on sentence and push it afterwards.

It should be simple

Often times, people easily criticize the framework by the look of documentation. Personally, I really don't care how documentation looks like. Appearance is completely irrelevant to it's purpose. As long as it's complete, concise, and readable, any format will do. Documentation could be plain text for all I care. Even Mustache's documentation are in "man page" format (here and here).