Before the whole internet on your phone thing, I often found myself reading anything when I am on the throne. Often times things like deodorant cans and shampoo bottles. I find myself retaining useless information like what the active ingredient is in my shampoo (Zinc pyrithione). I would sooo kill it in Jeopardy. What is Zinc pyrithione, Alex?

Now you may be wondering why I started out my blog post with my bathroom habits and my aspirations to be Jeopardy star. That feeling you have  wanting to read more is also the way I feel when I am reading good documentation. It’s smooth and very simple to read and allows you to get things done quickly. I remember Jacob Kaplan-Moss who is responsible for the django documentation (at least in part), saying that the intended audience should experience success in the first 30 minutes. Whether that be them using your tool, or they get something done that they couldn’t before. This is critical in two major ways:

1. It will keep then reading through the boring parts in hopes for other signs of win!
2. Praise your magic god like work.

Again for those information whores out, there here is the TL;DR version.

• Installation instructions that work.
• Cater to the masses.
• Tutorials, Tutorials, Tutorials.
• Ramp up to the hard stuff.
• Keep it up to date.

I have chosen docufail as my go to project. I will tell you a few things about docufail before I continue. It a very well written project programmatically, solves a clear problem, and even integrates well into many platforms. However, It is plagued with outdated and poor documentation. 

Installation Works

How many times have you seen documentation online especially (open source projects) is they claim to solve all your problems. Back pain? Yep. Trouble sleeping? Yep. Ugly? Of course, docufail can do that and more. It works on all platforms. So you go off reading and understanding how it works; then try to install and it doesn’t work. Then you spend the next three hours trying to troubleshoot an installation issue. Be very explicit on what platforms it works on, and what other requirements are needed. Make it easy for people to get started. Documenting your installation should be written for the dumbest person in your target audience, yes I mean the guy who misses his mouth when he eats. 

Often times people who write the documentation are the ones developing it. They have  a lot of context that others may not have. 

Protip: Do exactly what your documentations says once your done writing it. If it works success; if it doesn’t, rewrite. 

Cater to the masses

As you can see, docufail aims to solve a concise problem. There are people who will use it to solve that particular problem, but there are also people who have a slightly different use case with which docufail can help. At the beginning of your documentation, you don’t really care about the second group of people; you want to get as many people as possible to use docufail for its intended purpose. I have seen documentation start off with fringe benefits (internal APIs or extension points) before they even mention what problem it was built to solve. 

Tutorials, Tutorials, Tutorials

If your documentation doesn’t have a single tutorial, Go Kill Yourself™. The whole point of documentation is to get your user familiar with your project, and how it can integrate with other things. Often when I find popular projects with poor documentation, I constantly finding myself Googling the following:

docufail tutorial

When people figure something out after spending a couple of hours, they usually write it down so they don’t forget. The smarter and kinder among them put it online so others can find it. The documentation should contain this information not random blogs. Tutorial should be general in focus, allowing you to accomplish a simple task with a direct end result presented before the tutorial. 

Protip: Write tutorials on stuff that is basic and won’t change too often significantly. If this can’t be done, it should be in the reference guide and not a tutorial.  

Ramp up to the hard stuff

As I was saying before, you need to help your audience get work done, but you don’t want it to be too simple. Some people aren’t meant to be doing this stuff like a butcher, a baker, and candlestick maker to name a few. Make it easy, but not so easy that everyone can do it. This also provides a clear stopping point for those who don’t have the technical chops to continue. This should be stated at the beginning of any document. O’Rielly Media has two sections in every single one of thier books. 

1. What is this book?
2. Who is it for?

These are literally the two places where I look before I buy any book I am going to learning from, at least early on. Now I just suffer through the learning curve. 

Protip: Give your user insight on what the project is trying to achieve it will give them the correct context to understand why certain decision were made. 

Keep it up to date

If this were a guide on how to kill a project quickly, This would be the number one thing I would recommend: outdated and old documentation. Documentation should be gating any release of any tool, product or open source project. Nobody likes writing documentation, but that shouldn’t be reflected in the work. I can name numerous projects I have seen saying “documentation will get there” and they iterate 3 or 4 version ahead, you are just creating work yourself. 

Protip: Soon as you’re done a feature document it. Pass it around to people you work with who don’t know what you have been up to get feedback. 

Examples of great documentation

• Django - https://docs.djangoproject.com/en/1.3/
• Flask - http://flask.pocoo.org/docs/
• Tablib - http://docs.tablib.org/en/latest/index.html

Get to documenting. Have fun with it. 

Remember good code without good documentation isn’t good code. 

Discussion