As part of my final year project at university I had to create a web application allowing students to register for university. The requirements of this project had us write a minimum of 80 pages of documentation regarding the application, and it was honestly one of the most boring things I’ve ever had to expend energy producing. I wrote page after page of what is the biggest pile of tripe-masqueraded-as-documentation that I’ve ever produced. I didn’t want to invest my time in it. I would’ve much preferred to spend my time coding.

Fast-forward five months and I was working for a startup on their documentation team. Almost two and a half years later, I’m still working here and I love it. I love writing docs, I love exploring new products and new APIs and helping other people use them to create awesome things.

There is this idea when you are learning to code that documentation is something you just ‘have to do’ without an explanation of why it’s important. I’ve lost count of the number of times I’ve heard someone say “no one really likes writing docs”.  If you are creating a product, you are creating it for someone. And if you care about your users (which you should), you have a duty to help them use your product. Why build something beautiful if you aren’t going to provide a way for users to share in its beauty? Your product is never as intuitive as you think it is.

For me, realizing that the content I create can teach someone something was the difference between my boring-as-hell project and my I’m-actually-excited-to-go-to-work job. In my uni project I knew there would be, at best, one person reading it, but the true figure is probably closer to zero persons. I wasn’t empowering anyone. I wasn’t helping anyone. I was writing page after page just for the sake of it. Now, I’m writing for a user base of 1 million+ developers. It’s exciting to be part of the journey of these developers, giving them the ability to create, test, and publish apps by teaching them something that they wouldn’t have otherwise known.

If empowering people and helping them to use your product isn’t enough to persuade you that docs are cool, I guarantee you that writing docs for your product will make it infinitely better, even before your docs make it into the hands of your users. Developers and users interact with a product in different ways, but luckily for developers, writing docs will help you get into the mindset of your user. Docs are the best line of defense against bugs and UX problems that your users will inevitably run into. With good documentation, you will engineer a product that is better designed, less buggy, and creates a pleasant user experience for everyone. Everybody wins!

What type of documentation is best?

The type of documentation that is most useful to your users depends on the product. A game, an IDE, and a library all have different use cases and user bases, so you need to carefully consider the easiest way to explain your product and how to use it to all your users. This might include having more than one type of documentation. The following list illustrates items to contemplate when considering your documentation:

• Consider the type(s) of content that is right for your product and users. There are various different ways to document the piece of art you have just created, and you may need to use a variety of these to demonstrate the art: API, code comments, conceptual, videos, samples, tutorials, pictures, walkthroughs, diagrams, interactive workbooks, REPLs. Remember that everyone learns differently.
• Don’t use video content as your sole means of documentation. It’s lazy and it’s terrible UX. By all means have videos in addition to other content, but not on their own. It shows that you don’t really care about your users.
• Web-based tooltips should not be used in lieu of documentation. I’ll fight anyone who suggests otherwise.
• Consider the level of experience of your users. Don’t make assumptions about what they know, but also don’t be condescending.
• Bear in mind that English might not be someone’s first language. Try to ensure that you don’t use colloquialisms. (This one is especially hard for me – in Northern Ireland 90% of the vocabulary is colloquial)
• Within your code base: Add code comments where necessary, don’t add them just for the sake of it. Also have self documenting code – name your fields, methods, and properties something sensible.

If you are unsure what works, then take all the inspiration you need from other places (but please, for the love of god, don’t plagiarize, I can’t stress this enough. Plagiarizing is one of the worst things you can do!) Google, find what you like, talk to friends, ask people on Twitter. Some of my personal favorites are Parse, Go,and Twilio.

How to write documentation

I’ve explained at the why and the what, now we have to address the how. At its most basic, this can comprise of ‘Open a blank doc; start writing words; put it where users can read it’. No one expects you to write like Hemingway, but you can use the same set of skills that you possess as a developer to help you create great docs.

My good friend and colleague, Nina Vyedin did a fantastic talk on this at the Write the Docs 2014 conference with her talk ‘Hacking the English Language’, which you can watch below:

She explains that you can use the following common programming practices to help create your documentation:

• Don’t start with a blank page; create a template – If you create a templates for the docs you write, you have already put yourself halfway to finishing your next doc. There is nothing worst than staring at a blank page.
• Make a spec – You rarely start creating something in code without at least a thought-spec. You ask yourself ‘Who is the target audience’, ‘What is the current state of this product’,’What is the work plan’? This is also true for documentation, and keeping this spec in mind can help ensure your docs stay on track and are effective.
• Name your variables – Just like you would with variables in code, be specific, consistent, and deliberate in your writing. Clearly state your ideas and concepts, and explain them in the most concise way possible.
• Refactor your doc – Just as you would with code, rearrange, restructure and clarify your doc.

I use the lessons Nina teaches every day while I work, and I think they can be adapted regardless of the type of documentation or product that you create. Remember, just like good code, good documentation should be as concise as possible while still doing its job. It should be efficient, and shouldn’t clog up memory with unnecessary bits.

So please, if you care about your users, don’t forget the documentation. And if you don’t listen to me, listen to Miguel de Icaza. Dude knows what he’s talking about!

When I ask myself “what would have the most impact today?” I sit down and write documentation.

— Miguel de Icaza (@migueldeicaza) December 12, 2015