Software developers are known for being great programmers but bad writers. This is fair since coding is the software developers' core skill.
However, software developers contribute to internal or external documentation in many companies. And this is where software developers struggle.
This article shares tips to help you become a better writer and create better documentation.
1. Know your audience
Knowing your audience means understanding who you're writing for. Are you writing for experienced people or beginners?
Knowing your audience helps you evaluate whether you need to include or omit certain information.
For example, if you're writing content on "How to send an HTTP PUT request", you may want to specify what HTTP means if you're writing for beginners. If you're not, you can omit the information and your readers will still understand your content.
2. Be user-oriented
Technical writers are user advocates. They care about the user experience. If you want to improve your writing, keep your reader in mind throughout your writing process.
Writing user-oriented content means responding to users' intent.
If you want to write user-oriented content, respond to users' intentions - meet their needs before they realize they have them, and always be one step ahead.[Delante]
3. Logically structure your content
Structuring your content logically means laying out information so your reader can smoothly jump from paragraph to paragraph. Logical content feels clear and confusion-free.
Readers dont want bumps, unintended surprises or to feel threatened in any way. They dont want to follow a train of thought, only for it to lead to a dead-end, or for a new idea to be dumped on them without warning.[The Writers College]
How can you achieve a logical flow in your content?
Outline your ideas: Write the information you want your user to know on a piece of paper or editor. This step helps you clearly understand what you want to write.
Plan the flow of your writing. This step helps you visualize what works and what doesn't before you start writing, potentially saving you time.
Address each point at a time, and ensure there's a clear connection between paragraphs.
Use subheadings. Some readers read thoroughly, and other readers are skimmers. Write for both types of readers.
Use lists: use bulleted and numbered lists. Use bulleted lists when you want to list facts. Bulleted lists are ideal when the order doesn't matter. Use numbered lists when the order is essential.
4. Format your content
Formatting means how you want your content to appear. Formatting includes headings, subheadings, paragraph length, links, etc.
To format your content:
Use code blocks where necessary.
Break down lengthy paragraphs into shorter paragraphs.
Use H1, H2, and H3 subheadings accordingly.
Use tables to simplify content and data.
Edit and proofread. Editing and proofreading can be partially automated. Look for grammar and spelling errors. Ensure consistency in style and tone.
5. Write concisely
Concise writing means using the fewest words possible to convey an idea clearly.[Grammarly]
Some examples to help you write more concisely:
Eliminate unnecessary words such as in order to , and that. In order to is unnecessary 99% of the time. Replace it with To. For example, In order to install , would be To install.
Replace vague words with specific ones. For example, This helps you delete the branch without removing the entire history should be X command helps you delete the branch without removing the entire history. Being specific helps you avoid confusion and misunderstandings from the reader.
Use active voice as much as possible.
Conclusion
After reading this article, you have everything you need to become a better writer. Consider reading the following articles to learn more about writing:
Consider subscribing to my FREE weekly newsletter, I share useful content there!
Top comments (1)
I approve this message, that's solid advice right there.
The only thing is that the most powerful and simple way to write better
... is to just write often, in private, just for yourself, worrying about nothing else for now.
I should know because I worried way too much about how and where and when to publish my content when I started.
That's a huge recipe for procrastination and imposter syndrome and all that kind of stuff.
People vastly underestimate how useful it is to simply write for yourself.
Take the most simple app, like simplenote.com/ or icloud.com/notes
And write, just for yourself, as badly and as often as you can.
You won't believe how useful that is.