Quick tips for writing documentation

Photo by Olia Gozha on Unsplash

The following high-level overview offers a few tips to help your readers implement discoverable, relevant, and clear documentation.

Use short and specific titles

You want your readers to quickly glance through your documentation to find exactly what they want.

Document in an ordered and consistent way

When developing your documentation, you should create clear tasks in logical order for your readers.

For example, use a “Getting started” tutorial that goes over prerequisites and configurations, an installation guide, and a “Hello world” tutorial.

Create working examples

Your code examples, procedure, and tutorials should all run.

Your code examples should be use real world examples and should work, with minimal configuration from your readers.

Link to additional concepts

When introducing new or complex concepts for the first time, you should explain or link to where your readers can learn more.

Run your spell check

Running a spell check over your document will give some authority to your documentation.

Clean up sentences by simplifying them. This will also help prevent grammar mistakes. Keep your sentences short. Use one main idea per sentence.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Patrick Rachford

Patrick Rachford

Technical writer for AWS. I enjoy documenting my thoughts and sharing ideas with others.