How to judge documentation in 30 seconds.

Source: http://ericholscher.com/blog/2014/feb/27/how-i-judge-documentation-quality/

 

 A Website

If your documentation is a directory full of files on GitHub, I close the tab. With GitHub Pages, Read the Docs, and other places to host generated documentation for free, not making an effort is unforgivable.
If this is your project, please check out Mkdocs. It is still a new tool, but it will give your users something much nicer. I also recommend Sphinx for the most mature approach to documentation.

 

Prose

If your documentation is generated from source code, I am immediately skeptical. You should use words to communicate with your users, and those words shouldn’t live in your source code. If you included all of the things needed to document a project in source, your code would be unreadable.
So please, use a tool that allows you to write prose documentation outside of your source code. Your users will thank you.
A great start is to read this series on Writing Great Documentation, and the resources on the Write the Docs docs. [1]

 

Permalinks

One of the primary uses of documentation is the ability to link information to other people. If your documentation doesn’t have an easy way to link to sections of content on a page, then the value decreases. Your users should never have to send someone a link and say “go here and search for X”. That means your documentation has failed your users.
You’ll notice even my blog has permalinks. I believe all text content should, because it greatly increases the utility of the content.

 

URLs

There are two things I always look for in the URL:

• Language
• Version

Most often, projects don’t have either. Your URL should look something like: https://docs.project.com/en/1.0/

 

Versions

I see versions in lots of documentation, but not nearly enough. If your project has versions, your documentation should too. Not everyone can always upgrade to the latest version. If someone is using an old version, they should have access to documentation for that version.
Along the same lines, you should also have documentation for your development version. If the docs don’t have a version attached, I have no idea if they are up to date or not. You should clearly mark your released versions and development version, otherwise users will get confused.

 

Language

Language is one I rarely see. The software world has a nasty habit of forgetting that the whole world doesn’t speak English. If you don’t provide a language in your URL, you are implicitly sending the message that the documentation will never be translated.
I believe that translating documentation is a really important step towards helping people learn to program. Someone shouldn’t have to learn Programming and English at the same time.
Translations are quite a bit of work, so I understand why many projects don’t have them. But you should at least acknowledge the possibility of translation by putting the language in the URL.

 

Conclusion

That is the 30 second way that I determine if a project’s documentation is worth looking at. These are all hints about if a project actually cares about its docs. If the project doesn’t care about its documentation, that is a good sign that you probably shouldn’t use it.