A lazy developer is a good developer. Creating documentation is a waste of time. So a good developer does not like documenting.
Developers are wired different
As the introduction already states – developer hate documentation. Probably all developers by heart like working on their code, creating it, improving and solving hard problems.
Writing documentation – especially end-user focused product documentation – is not part of this. It feels unproductive (no code), and mostly not hard (since only some meaningless words describing obvious user interfaces and functions).
So how do I get my developer to document?
Make it simple. Offer them tools and automate as much as possible. Remove all manual, repeating work that is e.g. necessary to generate the documentation.
Provide insights and share customer feedback: share customer feedbacks, typical problems and unclear product features – to make them understand the documentation is not waste and provides necessary value to the user. They might even have ideas how to improve the product and make it more user-friendly.
Make it part of “done”: make it part of their work, and not let it slip. As soon as you do not check and request the docs, you are doomed.
Make it NOT their job: probably it does not make sense to waste their and your time trying. Talk to your sales, support or marketing teams and ask for volunteers. They are interested in good product documentation.
DevOps and agile world view – documentation is part of “done”
Documentation is part of finishing a feature or user story. If there is no documentation, the feature is not “done” in the agile world.
A lazy development team will search for simple, automated solutions. They like text editors, diff tools, writing with cryptic formatting code – and not using fancy, complicated tools as Word, taking manual screenshots, generating videos. So anything that requires them to leave their dev environment and toolset will probably not be done.
The solution is simple – use text files that are part of the product code repository. They can be edited and updated easily. Checking in code for a new feature will also contain the related test code for automated testing, and the basic documentation of the new feature.
Make it simple and use the right tools
Automate and optimize the production of documentation. There are tools and suites that help managing and generating documentation for a developer.
Todays tools are based on text-files, using Markdown to add some styling and links in a more human friendly way. Only a text editor is required to edit them. For example, most of the github projects have a README.md containing some information – using Markdown.
For creating and managing complex documentation, AsciiDoc provides a toolchain to generate documentation from markdown files to different output format as e.g. Html, PDF, Word and more.
Check out the website for more information https://asciidoc.org/#_overview_and_examples
To make the generated html pages more interactive and nice looking, additional tools as docsify can be used.
During the automated build process of the product, the documentation could be build using AsciiDoc, docsify and finally published automatically to a website. For private or small projects, github pages could be a simple solution. More information how to set it up in combination with docsify are described at https://opensource.com/article/20/7/docsify-github-pages .
For release notes and change log or knowledge base is
Good environments
The developer-centered documentation approach is well suited for simple, mostly technical products. It is not suitable for complex products with multiple-application products (e.g. featuring app, web app, backend, and different release cycles), and end-users that are not technicians.
It also works well for small teams without separat documentation team.
If the documentation is multi-language and needs translation, this approach will not work. Also, if “rich” resources as photos, screenshots or even videos are required, this will also not work since the production takes a lot longer.
Having a devops-centered, automated build & deployment process is a big help to implement it.
Suitable environments & positive indicators
- simple, technical product
- technical end-users
- small developer team, no documentation team
- documentation only in one language
- documentation has no or less rich resources
- devops-centered, automated build- & deployment process
Counter indicators for developer documentation
- complex, multi application products (backend, frontend, web app, mobile apps)
- non-technical end users
- bigger team size, and/or separate documentation role/team
- documentation in multiple languages
- documentation features rich resources including photos, screenshots and videos
- manual build- & release work by developers or operations team
Final words
For small teams and technical products, a developer-documentation centered approach with suitable toolchain and automation might work quite well. If possible, assign somebody from marketing or support team to support the developers and get a user-friendly, understandable documentation.
As soon, as the product & documentation gets more complex (multi-language, rich media-resources, multiple applications and apps) a separate documentation team is necessary.