In recent years, the concept of “Doc as Code,” also known as “DaC,” has emerged as a technical writing philosophy. DaC promotes the idea that the same tools that are used for software development should also be used for technical documentation. So, how do we go about putting Doc as Code into action, and is this approach appropriate for every technical writing project?
While technical writers create product documentation, content, and instructions, they have traditionally worked in a separate silo from developers. Writers may collaborate closely with developers, but technical documentation is typically kept separate from the code itself. For example, when companies develop software, technical writers usually write the documentation after the code has been finalized, and the developer has very little to do with the documentation process.
When we integrate Doc as Code into the process, however, we invite the development team to participate in the documentation process alongside technical writers. As a result, anyone on the development team can contribute to product documentation, and the information is owned by the entire team. The technical writing and coding teams use the same workflow management system, whether it is Waterfall, Scrum, Kanban, or another.
Doc as Code even extends beyond our workflow. This process helps us think about the way we actually create documentation. When we use the DaC process, we work in a plain text file system rather than using a program like FrameMaker or Word. Technical writers and developers collaborate during this process by using tools such as Git or Github. We also keep our documentation in the same location as the code, rather than hosting it elsewhere.
The “DaC” philosophy has sparked a lot of interest, but not everyone agrees that this process is the way of the future. Some technical writers argue that Doc as Code can be inconvenient, since writers may need to be familiar with tool sets like Python or Ruby. They argue that instead of focusing on technical knowledge and development, writers should concentrate on content. Another challenge of DaC is that it requires technical writers to meet developers in their lane with this process. What happens if the development process or toolset changes? Simple changes like image management or fixing a broken link can be time-consuming to update or correct in DaC.
However, treating documents like code has advantages. Because more people are contributing to the same solution, DaC can be more efficient and sometimes less expensive. By bridging the gap between the development and technical writing teams, you may be able to bring new ideas and better deliverables to the end users. DaC can also build a high level of trust and collaboration between departments.
Everyone needs to be on board to make the Doc as Code process work. If you’re the sole writer on the project, it may not be worth your time to implement DaC. The good news? You can borrow the parts of the process that work for you and eliminate the parts that don’t. Both writers and developers need to feel confident about the final documentation, and there’s no single solution for every organization.