Do you write documentation? Most developers love to write code. They write code that solves problems. It helps people to get something done. If they write documentation, it is quickly written. A task to be completed so you can get back to writing code.
Image by Christine Sponchia from Pixabay
How do you choose a new framework? You look at the features to see if it does what you want. Then, you read the documentation. If it is hard to read or non-existent, you’ll get frustrated and choose a different solution.
If you want people to use your code, you need to write great content.
How do you write better documentation?
- Decide who you are writing it for
- Decide what you are going to include
- Make it easy to use
- Keep it up to date
- Read great documentation
Decide who you are writing for
You need to know your audience. Are they developers, clients or customers? Developers want to know how to use your code. Or what can they do with it. Your clients may want step by step instructions on how to use it.
What are you going to include
Decide on what you want them to know. Create a list of questions or items that you need to cover. A technical audience may want to read tutorials, how-to-guides and/or references. Beginners learn better with simple step by step instructions. For everyone, you may want to include videos as well.
Make it easy to use
No matter what you are writing, decide how you are going to organize it. If you are writing a tutorial, you may want to start by explaining what you are planning to talk about. Use formatting styles like headings, bulleted or numbered lists and bold or italics. Formatting styles help guide the reader through your documents.
Keep it up to date
Developers make improvements and changes to their code. When they do, the documentation needs to change as well. Plan time to update it. Apps and other projects fail because the content isn’t kept up to date.
Read great documentation
You can learn how to write better by reading. These style guides show you how to write great developer content.
- Microsoft’s Style Guide for Developer Content
- Google Developer Documentation Style Guide
- Mailchimp Content Style Guide
- Basecamp Guide to Internal Communication
More Resources
- In The Developers Guide to Content Creation, Stephanie Morillo teaches you how to write. You can use her suggestions for a blog, newsletter or documentation.
- Write the Docs Community is a global community of people who care about documentation.