Article summary
One of the more frustrating things as a designer is jumping on a project or using a tool with poor documentation. For me, this process can be pretty stressful, and there is typically a large gap in knowledge between the developers and designers.
The developers might think installation and setup is super-simple, wondering, “Why can’t they just get it up and going?” Meanwhile, the designers might be thinking, “I have no idea what these directions mean.”
Writing documentation at a more basic level could be a welcomed solution. Consider who will be interacting with a tool or program. It may take a bit longer up front, but it could save a lot of time down the road.
Need-to-Know Information
Your documentation should answer basic questions like these:
What is the tool for? What can it do?
Yes, this is basic, but a short sentence or paragraph describing what the tool or program is for can go a long way toward lowering the barrier to entry.
How do you set up an environment?
Please give step-by-step instructions to get the environment set up from scratch. One major culprit is listing dependencies without a link or any information. If there are obvious places where we might go astray, please leave a note to help us get back to the right trail.
How can we use it on a daily basis?
Now that we have the tool or program set up, how do we use this thing? Providing basic and advanced sections of the instructions may be a win. The advanced section could be a place for commands that could lead to major issues with the environment. By separating the commands, you might help novice users feel more comfortable interacting with the program.
Where do we go to ask questions?
When we find ourselves stuck, where do we turn for help? You can also let us know if help is not available at this time.
How can we submit issues?
If we find something wrong or want to see a section improved, where do we send the request? What does the process look like? Is there a process?
I know it takes a lot of time to document and set up a simple process. But from someone who has drawn the short end of the stick a few times, it would be greatly appreciated.
Examples
Here are docs that do it well:
- http://getbootstrap.com/getting-started/
- https://codex.wordpress.org/Installing_WordPress
- https://github.com/meteor/meteor
What helpful tools do you use to keep documentation and instructions up-to-date?