Docs as Code - The New Way of Creating Documentation

Table of Contents
General
Docs as Code

In this blog issue, you will learn some basic insights into the philosophies of technical writing, as well as insights made by specialists and experts in this area of writing. What do technical writers do? Quoting from T. R. Girill's paper on "Philosophy's Relevance to Technical Writing," we can say that "Technical writers prepare research reports, proposals, instruction books, and newsletters for medical centers, manufacturing firms, financial institutions, and government laboratories." Of course, this represents only a small area of use cases for technical writers, and there are many more you can imagine. Let's first concentrate on the technical writing of handbooks. Ryan Brong makes this point clear on his blog "Ryan Brong's ePortfolio," where he writes that engineers and scientific researchers need to bring their ideas to the public by using great technical communication.

Many businesses and sectors rely on technical writing for essential communication. Simplifying complexity, technical writing enables clear understanding and implementation of ideas, theories, practices, or procedures.

It holds immense relevance for businesses and sectors employing user documentation, instructions, technical reports, feasibility studies, corporate reports, research results, policies and procedures, business plans, white papers, case studies, literature reviews, proposals, and more.

Technical writing, present since the inception of written languages, is experiencing rapid growth, particularly in our advancing era of telecommunications. Its popularity shows no signs of waning and will remain integral to our world for decades to come.

So, what does that mean, and how does this work?

Technical writing simplifies complex ideas, making them easy to understand and implement in different contexts such as user documentation, reports, studies, and plans.

Essentially, technical writing involves conveying technical information clearly and effectively. It ensures that complex concepts are presented in a manner that is accessible to the intended audience. This can involve breaking down intricate processes, explaining specialized terminology, and providing clear instructions.

In practical terms, technical writers analyze the audience, gather relevant information, organize content logically, and communicate it using appropriate language and formats. They strive to make technical content understandable and usable for readers who may not have a technical background.

Overall, technical writing plays a crucial role in facilitating communication and knowledge transfer within businesses, industries, and sectors, ensuring that information is conveyed accurately and comprehensively.

There are 5 components of technical writing

The components of technical writing are fundamental for creating effective communication materials. They include:

1. Purpose: Clearly defining the reason for the document and what it aims to achieve.

2. Target Audience: Identifying the intended readership and understanding their knowledge level and needs.

3. Content: Providing accurate and relevant information to fulfill the document's purpose and meet the audience's requirements.

4. Organization: Structuring the content logically and coherently to facilitate understanding and navigation.

5. Style: Using appropriate language, tone, and formatting conventions to enhance readability and convey information effectively.

There are 7 types of technical writing

As for the types of technical writing, they encompass a range of documents tailored to different purposes and audiences. They include:

1. User Manuals: Instructions and guides for using products or systems.

2. Standard Operating Procedures (SOPs): Detailed instructions for performing specific tasks or operations.

3. Technical Reports: Documents presenting findings, analysis, and conclusions from research or investigations.

4. White Papers: Authoritative reports addressing complex issues, often used for business or technical purposes.

5. Proposals: Formal documents proposing solutions, projects, or collaborations.

6. Online Help Documentation: Digital guides and resources to assist users with software applications or websites.

7. Scientific Articles: Papers presenting research findings and analysis within the scientific community.

An example of technical writing could be a user manual for a smartphone, providing step-by-step instructions on how to set up, operate, and troubleshoot the device. Such documents aim to empower users with the knowledge needed to use the product effectively and efficiently.

Technical writers face several disadvantages. Firstly, tracking changes in purely text-based programs can be challenging as they lack integrated versioning features. Secondly, automated tests to identify and fix documentation errors early are absent. Thirdly, organizing and reusing content in purely text-based environments can be cumbersome, leading to inconsistencies. Fourthly, deploying updates is slower without integrated processes to automatically publish changes. Lastly, achieving automation and efficiency in the publishing processes is not straightforward.

The solution for technical writing is Docs as Code

"Docs as Code" represents the optimal method for creating technical documentation. The documents are coded within an application, enabling users to utilize the content, format it, maintain it, and distribute it across various devices and mediums.

"Docs as code" is a methodology that treats documentation as an integral part of the software development process, rather than an afterthought or a separate task. It applies principles and practices from software development to the creation, review, and maintenance of documentation.

Here are some key aspects and benefits of the "docs as code" approach:

1. Version Control: Just like source code, documentation is stored in version control systems such as Git. This allows for tracking changes, collaboration among team members, and reverting to previous versions if needed.

2. Text-Based Format: Documentation is often written in plain text or lightweight markup languages like AsciiDoc, Markdown or reStructuredText. These formats are easy to read and write, and they can be converted to various output formats such as HTML, PDF, or EPUB using tools like Sphinx, MkDocs, or GitBook.

3. Automation: Continuous integration (CI) and continuous delivery (CD) pipelines can be set up to automatically build and deploy documentation whenever changes are made to the documentation repository or the codebase. This ensures that the documentation is always up-to-date and in sync with the software.

4. Collaboration: Since documentation is stored alongside code in the same repository, developers and technical writers can collaborate more closely. They can review each other's work, provide feedback, and make changes together, fostering better communication and shared understanding.

5. Reusability: Documentation components such as code snippets, configuration examples, and troubleshooting guides can be reused across different projects or modules. This reduces duplication of effort and ensures consistency in documentation style and content.

6. Testing: Just like software, documentation can be tested to ensure accuracy, completeness, and readability. Automated tests can be written to validate links, code samples, and other aspects of the documentation.

7. Feedback Loop: By treating documentation as code, developers are more likely to engage with it actively. They can suggest improvements, report errors, or request clarification directly through the same channels they use for code contributions, such as pull requests and issue trackers.

8. Agility: Adopting a "docs as code" approach allows teams to iterate on documentation quickly and respond to changes in the software or user feedback more effectively. It promotes an agile mindset where documentation evolves alongside the codebase.

In summary, "docs as code" promotes a culture where documentation is valued as a first-class citizen of the software development process. By applying principles of version control, automation, collaboration, and testing to documentation, teams can create and maintain high-quality documentation that enhances the overall user experience and developer productivity.

Can I use docs as code for other technical writing?

Yes, the principles and practices of "docs as code" can be applied to various forms of technical writing beyond traditional software documentation. Here are some examples:

1. API Documentation: Just like software documentation, API documentation benefits from version control, collaboration, and automation. With "docs as code," API documentation can be stored alongside the codebase, ensuring that it remains accurate and up-to-date with each software release.

2. System Documentation: Documentation for systems, architectures, and infrastructures can also be treated as code. This includes network diagrams, system configurations, deployment procedures, and operational runbooks. Storing this documentation in version control allows teams to track changes and ensure consistency across environments.

3. Technical Guides and Tutorials: Guides and tutorials that explain how to use software tools, frameworks, or libraries can benefit from the "docs as code" approach. By storing them in a text-based format and leveraging automation tools, authors can quickly update and publish guides to reflect changes in the technology landscape.

4. Training Materials: Training materials for onboarding new team members or educating users on how to use a product can be managed as code. By treating training materials as part of the documentation ecosystem, organizations can maintain a single source of truth for all instructional content and ensure that it remains relevant and accessible.

5. Compliance and Regulatory Documentation: Documentation related to compliance requirements, such as security policies, data privacy regulations, and industry standards, can be managed using the "docs as code" approach. Storing compliance documentation in version control helps organizations track changes and demonstrate adherence to regulatory requirements.

6. Internal Knowledge Bases: Internal knowledge bases, wikis, and documentation repositories can benefit from being managed as code. By storing knowledge base articles and internal documentation alongside the codebase, organizations can ensure that tribal knowledge is captured and accessible to team members, regardless of turnover or organizational changes.

7. Configuration Management: Documentation related to system configurations, environment setups, and infrastructure provisioning can be managed as code using tools like Terraform, Ansible, or Puppet. Storing configuration documentation alongside infrastructure code ensures that changes are tracked, reviewed, and documented in a consistent manner.

In summary, the "docs as code" approach is not limited to software documentation but can be extended to various forms of technical writing and knowledge management. By applying version control, automation, collaboration, and testing to technical documentation, organizations can improve documentation quality, maintainability, and accessibility across different domains and disciplines.

Docs as code versus Microsoft Word

Working with Office file formats like Microsoft Word allows users to locally edit, print, and share documents via email or file storage with other authors. Depending on the infrastructure, documents can be collaboratively edited via SharePoint or OneDrive. However, it becomes challenging, especially when different edited document versions need to be merged across organizational boundaries. An alternative to this approach is using wikis, where authors collaborate on documents. The process of formatting content into print-ready documents with attractive layouts is often cumbersome. Both approaches reach their limits when writers are required to maintain different versions of documents concurrently, for example, for different releases or products.

For newcomers in technical writing using such systems, several platforms have evolved over time. Markdown, AsciiDoc, and reStructuredText are just a few examples. They offer several advantages, as they are readable and editable in any text editor. Through conversion, content from the source texts can be transformed into other formats, such as high-quality HTML or PDF documents. They include various components such as headings, cross-references, and tables of contents. In contrast to traditional word processing, transitioning to such a format requires a different approach to document management. Check out our blog post on creating a user manual in AsciiDoc for a practical example.

Let's talk AsciiDoc

AsciiDoc is well-suited for technical writing in Docs as Code due to its clear, structured, and easily understandable syntax, which is particularly suitable for documenting software projects. With its simple Markdown-like formatting, developers and technical writers can effortlessly compose complex concepts, code examples, diagrams, and instructions while maintaining a clear separation of content and formatting.

AsciiDoc also supports integration with version control systems like Git, facilitating seamless collaboration and version control. Additionally, it offers a variety of extensions and integrations for automated document generation in various formats such as HTML, PDF, and ePub. Overall, AsciiDoc provides a flexible and powerful platform for creating and managing technical documentation within the realm of Docs as Code.

AsciiDoc with adoc Studio

The downside of AsciiDoc is that if you are not a tech-savvy person and simply want to focus on writing, you still end up spending a lot of time in a code environment. However, there's a great solution available to address this issue. It allows you to compose your technical documents with AsciiDoc on your Apple devices, whether it's a Mac, iPad, or even iPhone.

You can apply all attributes from the AsciiDoc syntax and simultaneously see the result in real-time. Afterwards, you can style the document's appearance and export the content in various formats. Be sure to check out adoc Studio if you are serious about technical documentation using the AsciiDoc language.