Quick tips for writing documentation
One aspect of developing and maintaining a successful software project is to write clear and concise documentation.
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.