Nothing is more frustrating to me as a computer programmer than trying to integrate with third-party software that is not documented well. I often say it’s like feeling around in the dark. Rather than clearly seeing how to accomplish my goals, I’m forced to feel around, trying many different things until I can finally come up with the results for which I set out.

On the other hand, when someone takes the time to document their product or process thoroughly, it makes life so much easier for everyone who uses it. I know it’s not fun. Not many people love documenting their work. But most people, if you ask them, want to help make the world a better place. Make someone’s day a little better by writing good documentation.

Here, I’ve outlined some tips to improve your documentation:

Add the Extra Details

What’s obvious to you isn’t always obvious to another. If your documentation starts to become too cluttered, consider using an appendix or including helpful links. Simply by adding a link, you’re saying, “It’s okay not to know what this is – go here to learn more,” making the documentation more inclusive and welcoming.

Keep it concise

Huge paragraphs and essay-like blocks of text are intimidating. Most readers will skim over them. Make it easier for the reader to see the important bits at a glance using these tactics:

  • Use two to three sentences per paragraph.
  • Include bullet points
  • Highlight important info with bold or italic formatting. For example, add strategic bolding in the first sentence of each paragraph and use regular font for the supporting details. (see what I did there?)

Use Screenshots

A picture is worth… a lot of words. Visual aids help clarify your documentation, making it easier to understand and apply.

Review and test for accuracy

To make sure your documentation is complete, recruit a colleague to review it. If they have questions or make mistakes, you’ll need to make some revisions.

Don’t just document well for others… do it for you! You’ll get fewer support requests or follow-up emails. Also, chances are that six months from now, after working on dozens of other things, you’ll forget why or how you did something, especially if it was a clever something.