Why is documentation treated differently than the product?

Documentation is an often-underappreciated part of the products we create. Despite documentation’s important role in delivering a complete product, it may not receive the same priority in the minds of both clients and development teams. Why is documentation treated like a separate entity from the product itself, and what if teams integrated that product documentation into the development workflow instead? This question led to the creation of a new documentation process by technical writer Riona Macnamara and her team at Google. Macnamara’s team created a method for adding docs into a product’s development by adding documentation to the product on the code level, instead of treating docs like a low-priority add-on.

Anne Gentle explained Macnamara’s process in the book Docs Like Code, which was the inspiration and primary resource for our experiment. Innovation at ITX doesn’t stop at development. We always seek opportunities to optimize processes across a product’s life cycle, including experimenting with new strategies and techniques to enhance client deliverables. So, it was natural we should investigate the Docs Like Code (DLC) process to determine if it would add value to our offerings to our clients.

DLC in action

For our initial experiment with DLC, we wanted first to understand how the process changed the content side of a project. We chose content because DLC changed the typical ITX content process and required the content team to familiarize itself with Git repositories; in contrast, a dev team wouldn’t have that requirement.

Training content team members on the developer tool package (Git repositories) was the first phase of the experiment. After a week, the content team could draft in Git. The team found the process was like using Word, especially when using a formatting resource such as Markdown.

Refocusing documentation through tool sharing

The major model shift of DLC involves organizing the documentation process to prioritize the development team’s needs. DLC uses developer-centric tools like GitHub and Markdown over writer-centric tools like Word or Google Docs. This change encourages regular, timely documentation created with tools developers already use without needing to change toolsets to create documentation. Git also provides a regular model for documentation storing, by keeping all document files in the product directory. Using shared resources between teams helps document iteration as the project evolves. Since developers already work in Git, they do not need to change tools to write or review documentation. Git also enables workflows that automate technical documentation delivery alongside code updates. DLC helps create a mutual relationship between documentation and code that encourages developers to create or review documentation as a requirement for publishing code. That process change means accurate documentation ships with each new update.

No technical writer, no problem

When this process was developed at Google, it assumed the use of a technical writer attached to the project development team. However, a technical writer is not required for development teams to use this workflow. In place of a technical writer, the development teams would rely on a documentation practice of standards established by their practice manager, with each sub-team owning the documents connected to their specialty.

An example of how this might look:

• QA maintains QA documentation
• Software Engineering maintains ADRs (architecture decision records) and relevant documentation
• Product maintains relevant documentation
• Project Management maintains relevant documentation
• UX maintains relevant documentation

Why this matters

Should a development team prioritize documentation and change their workflow by adapting DLC? Yes and no.

Yes, a development team should prioritize documentation. Clients expect accurate and easy-to-locate documentation shipped with products. Encouraging development teams to embrace documentation improves the deliverables ITX provides to clients.

Is a development team required to change their workflow by adopting DLC? That’s the neat part. No.

Adopting DLC doesn’t require a change in the development team’s workflow. Using DLC moves the focus of documentation, making it a necessary part of the coding process instead of a secondary element worked on separately from the code. 

Key take aways

Working with subject matter experts, other writers, and version control was much easier when using Git repositories. Tracking changes through merge, branch, push, and pull updates improved the sometimes-chaotic sharing process typical with SharePoint. Similarly, the standardized version control removed a key pain point among the team, since the team could sometimes miss tracking a change using their traditional editing process. The team used the ‘index.md’ repository for all documents making locating those files easy.

Another feature the content team liked was the potential offered by validation checks through custom scripts. This automatic proofing made reviewing and correcting formatting errors, broken links, or improper terminology easier, faster, and more accurate

Conclusion

Ultimately, the content team found the DLC process improved the documentation quality and reduced time between version updates. The DLC process deserves more experimentation but offers the opportunity to improve how ITX potentially plans for and creates product documentation in the future.

---