Documentation is something, at least in my experience, that gets cut from release or partially included because some feature has to ship or… any number of noisy excuses. Really, it’s the work that very few want to do - those supporting the application or product probably do not think of it, the testers likely do not have time, developers would rather code than write documentation, etc.

This is extremely unfortunate because usable documentation will help your users, support staff, developers, business analysts, and customers make better use of your product. Microsoft has apparently heard this from customers long enough that documentation has become not only popular inside the company, but open sourced so you can help the process of submission, cleanup, testing, and anything else you can think of.

I know that not every company is going to put their documentation in GitHub, and end up buying the company as a result of usage (yes there were other factors, but docs.com was certainly a big one I am sure), but every company that produces any kind of software or product in general should be willing to invest the time to write documentation. Remember, customer service starts before the user calls to ask questions - if they do not need to call because a well written F.A.Q. or user manual can get them what they need, they will use it without thinking about it.

I think that the smartphone has made the least used feature for nost people, the phone. Calling for things in the information/connected age is just a hassle - this is an opportunity for documentation writers/engineers/developers - put the best of the best online and help the customer where they are - don’t make them call so a technician or customer service rep can read a script of what to do - likely written by the docs team, help them before they get that far with usable documentation.

I am not trying to bag on any customer service experience or the people that provide these services, consider for a moment that many people are not in the best of moods when they reach out to a “somebody” at a company for help. Likely because they couldn’t find or use the product documentation to solve their issue… then they had to CALL… what a hassle - and sitting in phone tree hell for “3 minutes going on 30” to be transferred, redirected, misdirected, asked to call back, asked to leave a message for a return call… ugh.

The short of it is, make the documentation part of the project/process from day one. Getting to Minimum Viable Product should include docs. If your project doesn’t include documentation… it may be minimum and product, but is it viable? Will your users in the wild be able to get around it without documentation? Some will, many won’t and figuring out how to rework well written documentation into the backlog after the project completes will likely be an exercise in futility as nobody will want to fund this rework.

##What makes usable documentation? There are lots of things that make documentation usable. Here is a brief list of things I think make documentation usable:

• Be brief - don’t use 25 words when 10 will do
• Use screenshots - always include a screenshot to show someone where to click, it keeps the documentation brief and on point (see point 1)
• When writing documentation, be the user - work on the documentation while following the steps you are documenting.
• Keep it alive - things change, steps shorten - make your documentation a living entity and update it regularly
• Ask others to work through it to know it works on other machines

This list isn’t exhaustive, but these things are items I have found in writing documentation other technical work that keep things moving and reduce questions to support or development.

Oh and take feedback - leave a way, right in the docs, for the reader to reach out. If they have suggestions or notes about things that could be different, at least give them a way to pass these along - then READ THEM! Remember, if your users can help improve your documentation, you should embrace that and be happy they are willing to help.

##Is all usable documentation good? That is debatable - I have seen documentation that I could muddle through and get what I needed, but it was a bit of a chore, which would lower it on the scale of bad to good. I chose usable in this post on purpose - the more usable you start out, the faster your documentation will improve. And usable documentation is certainly better than completely unusable documentation - which does exist… do some googling, surely there will be examples of both.

##What tools make documentation usable? No tool in itself makes documentation, let alone usable documentation - remember, computers do what they are told and nothing more - if you tell a computer that 1 + 1 is 3 in a program somewhere, that software will always produce that result when your condition is met.

You need to consider the audience and platform for your documentation before worrying about choosing a tool. I have used a few tools to produce documentation from the free to the not so free and both categories have things I love and things I do not use.

If one tool had everything it would likely cost too much to consider. Try to keep your documentation source in a single environment, that is use an editor that supports your output format (and multiple if you need that). Don’t bounce the source between editors to gain a feature. If you need PDF and Markdown, find a tool that does both - OR if you have tools you really like for PDF but they do not do MarkDown, keep 2 copies of your source one for each. That will require workflow to ensure both are updated to match - so your documentation is usable in both formats.

It is really up to you which tools you use and how you use them. Keep your source in source control (think Git or SVN or even offsite backup) to ensure it is kept safe and available and you should be ok no matter which tools you choose. And keep these tools updated - if there is an update available that does not break something you must have, ensure it is installed.

#Ask for feedback Yep - I used a giant header… on purpose - Ask for feedback!

The last thing I want to call out, again, is feedback. Yes, put contact information in the documentation and read the comments, questions, rants, and raves that come in, but also make sure to survey your users (internal and external) periodically to ensure the documentation is meeting their needs and exceeding their expectations. You do not need to spam them weekly with this kind of thing, but when you get rolling on an update to the documentation - maybe send a note to existing customers or users to let them know that there will be updates soon and ask them if they have any feedback - or suggestions about how things can be improved.

Documentation can be fun to build and certainly should not be an after thought. With open communication, good feedback loops, and inclusion in the MVP of a project/product there is no reason I can think of that usable documentation is something that will elude anyone.