Documents are an integral part of a developer's experience in the Platform Engineering era. The docs allow DevOps and Infrastructure teams to share knowledge that will enable autonomy and self-service in development teams, but what if there are too many documents and notes? This can be a direct detriment to the development experience and can even be a waste of time for the readers.
How will we create effective documents that will improve DevEx and not harm it?
Writing correct and concise documents is the most basic principle. There are many courses and guides on the internet that will help you understand the basic principles of writing technical documents for developers, but this is not enough, get 5 more principles:
Use one documentation tool. I often come across organizations that have not decided on one documentation tool—some organizations even use three or four tools, but they all provide the same value. Choose the tool that is most convenient for your users and only create the documents with that tool; that way, you will avoid switching between tools and wasting time on searches.
Adapt the language and terms to the target audience—do not use concepts that the readership is not familiar with. Confusion and learning new terms that are not necessary for understanding the main topic in the document may cause a delay in understanding and readers might even give up on continuing to read the document, which may contain very important details.
Use central templates that will allow readers to know in advance what they will find in each part of the document. Tools often provide templates as part of their service, but you can find many templates around the internet.
Keep the docs updated. Out-of-date documents can be misleading and probably waste time, but they can also damage your credibility and thus readers will give up on reading more documents in advance.
Last but not least (and most important): use integration with the development tools. There are tools that interface directly with the development tools (Git, IDE) and management (Jira, Monday, etc.), and these tools have a significant advantage in terms of cognitive load. Developers can view information through the daily tools they work with—without getting out of the development "bubble" and poking around in the dark worlds 👹 of documentation or other teams.
➕ Bonus Section: Platformerz Recommendations ➕
Kommentarer