Listen to this article
Documentation is critically important for developers, both as a resource and as a logging method. Every developer should care about documentation, regardless of its type.
So how can devs ensure proper documentation during the development process? What tips and tricks can developers use to guarantee they’re optimizing their logs?
Read on and discover more about the art of documentation every developer can follow.
Documentation 101
What does “documentation” mean for developers? It can refer to many different things, such as:
- README files
- inline code comments
- documents auto-generated from a source code
- Wikis (e.g. Confluence)
- And more
Developer documentation benefits
There are many benefits when a developer writes documentation. These include:
- An explanation of how the code works and what it does
- An explanation of features
- A chance for others to get involved
- Assistance to quickly recall your task at hand and why you’re doing it
- Assistance to track code changes and the reasons
Why is documentation important?
Documentation is important for developers for three primary reasons:
Improves Productivity
When a developer writes documentation, productivity is boosted via:
- Decreasing catch-up time
- Minimizing repetitive questions, problems, or concerns
It’s good when people have questions that they can ask so as to learn, but it takes up a lot of time when multiple people have the same question, problem, or concern. Having documentation in place for people to reference is a great way to decrease time-consuming repetitiveness.
- Decreasing delays
When people are on vacation or out of the office for any reason, waiting for their reply on an issue that they only know how to address can be quite frustrating, and can cause significant delays in development. But a developer’s documentation that is established for people to use and learn from will never be unavailable.
Writing forces “Dogfooding”
Writing documentation often forces developers to engage in “dogfooding.”
“Dogfooding” is when developers use their own product or service to test it before it’s released to the public, clients, or customers.
The disconnect that some developers have between themselves and what they are working on is because they don’t use the product or feature set before them.
But by writing documentation, developers can ensure they’re “dogfooding” their product or service effectively and efficiently, thereby testing the experience and its usability before it’s released.
Documenting code reveals Bugs, Vulnerabilities and Problems
Writing documentation and keeping your information current is one sure way to reveal bugs, vulnerabilities, and potential problems. By writing and reviewing documentation, you are preventing yourself from assuming the way your code works (or if it works at all), and thereby seeing your system from a different perspective — the user’s perspective.
Tests can certainly reveal bugs, vulnerabilities, and issues, but they cannot check experience or usability. Writing and reviewing documentation will give you the time you need to ensure you’re seeing it all from the user’s perspective whilst avoiding previous assumptions you have easily made in the past.
But how do developers write satisfactory and well-written docs? Discover eight steps to take to conquer the art of documentation writing for developers.
8 Steps to the art of documentation writing for developers
When a developer writes documentation, it doesn’t have to be dry, dull informational content; rather, it can be engaging, interactive, and efficient.
How?
Step One: Give your documentation a home
If you centralize your documentation, people will always know where to go to find the answers they need. Ensure your documentation has navigational elements to lead users to alternate areas that provide the other information they’re looking for.
Step Two: Make use of feedback
What has been helpful? What hasn’t been helpful? Write your documentation as if you are a new developer, and give thorough explanations and informative details.
Step Three: Make documentation appealing to the eye
With the use of many documentation tools (e.g. text highlighters, special tabs, etc.), developers can create nice-looking, readable code samples that are appealing to the eye.
Step Four: Provide additional information
Whether it’s for successful onboarding, cross-referencing, or other learning opportunities, providing additional information in your documentation as a developer will immensely help your reader. This additional information can be in the way of FAQs, additional resources, and other learning materials.
Step Five: Use various kinds of content.
As a developer, you will most likely be using text and code samples, but that is not all you can use to present your content. In fact, you can use screenshots and screencasts as well to give explanations or display information.
Step Six: Explain the changes
There are two important reasons to remember to explain when something changes:
- To help people understand why something changes.
- To provide a resource for later reference in case someone forgets why something was changed.
Step Seven: Keep documentation up-to-date
Software products change rapidly (oftentimes with new features every three to six months), so it’s important to keep your documentation current and relevant. Developer documentation should always reflect those changes and updates. Establish a plan to ensure you’re keeping your documentation up-to-date for your readers.
Step Eight: Use the cloud
You can not only use cloud tools to create your content, but you can use them for publishing it, too. Your team will all have access to the same environment, and you can access your information from any device anywhere you are. All tools that you use should provide features for collaboration, customization, single sourcing, content reuse, translation, localization, analytics, and reporting.
By taking these eight steps, and using tools with the features listed in step eight, you — as a developer — will write engaging and effective documentation.
