2 posts tagged with "medium"

In my previous article, Docs-as-Code Methodology and Advantages, I provided an overview of the Docs-as-Code methodology and its general advantages. In this article, I will delve into the specific benefits of integrating Docs-as-Code, discuss the tools used, present an example of the Docs-as-Code workflow in your team's development process, and explain the significance of Docs-as-Code tools.

Integrating Docs-as-Code​

When contemplating the documentation process and whether integration is worthwhile, it's essential to consider who will be responsible for authoring the documentation. If this responsibility primarily falls on the shoulders of technical writers, the choice of tools may not be as critical. However, if developers are actively involved in the writing process, embracing Docs-as-Code and integrating suitable writing and publishing tools into the development workflow can yield significant advantages. By "suitable tools," I refer to developer-focused programs, tools, version control systems, and collaboration platforms. These tools are well-known to developers, enabling them to seamlessly participate in documentation production.

What "Docs-as-Code tooling" exactly stands for​

Docs-as-Code, in essence, involves applying the same principles and practices to your documentation as developers do to their code. Therefore, when referring to "Docs-as-Code tooling," I'm talking about embracing tools and approaches that are familiar to developers:

Working with plain text files: In Docs-as-Code, documentation is authored in plain text files, steering clear of proprietary binary formats like Adobe FrameMaker or Microsoft Word. Plain text files are more conducive to version control and collaboration.

Leveraging static site generators: An essential aspect of Docs-as-Code is employing open-source static site generators like Sphinx, Jekyll, or Hugo. These tools empower you to build documentation locally via the command line, a departure from commercial software like FrameMaker or Word.

Utilizing Text Editors: To align with Docs-as-Code principles, authors prefer text editors such as Atom or Sublime Text. These editors foster a transparent, code-like approach, in contrast to closed, proprietary tools that operate as enigmatic black boxes.

Storing documentation in a version control repository. Docs are stored within version control repositories, commonly Git repositories, much like how software code is managed. This approach replaces conventional storage solutions like SharePoint, Google Docs, or shared drives. In some cases, documentation may even reside in the same repository as the codebase it documents.

Using collaborative version control platforms: Collaboration in Docs-as-Code hinges on version control systems like Git. Writers employ the same approach as developers: branching, merging, pushing, and pulling to facilitate seamless collaboration. Technical Writers can use GitHub for Desktop to alleviate the adaptation. In this case, they don't need to work with a CLI and memorize a bunch of commands to manage documentation within a repository because GitHub for Desktop offers an intuitive user interface, which allows getting started with minimum knowledge.

Automated site building: Automation is a cornerstone of Docs-as-Code. Continuous delivery pipelines automate the generation of web-ready documentation whenever changes are pushed to a specific branch. This eliminates the need for manual publishing and file transfers.

Validation through custom workflows and scripts: Custom workflows and scripts play a vital role in Docs-as-Code by automating validation checks. These scripts can identify broken links, sidebar discrepancies, code owners, pull request (PR) labels, incorrect terminology, formatting discrepancies, and other errors, reducing the reliance on manual content inspection.

Agile documentation management: Docs-as-Code aligns documentation processes with agile development methodologies, such as Scrum. Documentation work is structured into manageable chunks, tracked in an issue management system like Jira, assigned to bi-weekly sprints, and progress is regularly reported to stakeholders, often involving live demonstrations.

In summary, adopting Docs-as-Code entails applying the same systems, workflows, and best practices to documentation that are commonly employed in software development. This approach enhances collaboration, version control, and overall efficiency in managing documentation projects.

Example: Docs-as-Code documentation development workflow​

Let's dive into a practical example of how the Docs-as-Code documentation development process can work in a real project. Let's consider a scenario where a software development team is using Docusaurus for documentation, Jira for issue tracking, GitHub (or GitHub desktop as an option for technical writers) for version control, and S3 for storing images.

Step 1: Issue creation (Jira)​

1. An epic or user story is created in Jira as part of the development process.
2. A documentation ticket is automatically generated in Jira and linked to the epic or user story.
3. During the planning phase, the product owner (PO) or product manager (PM) identifies the need for documentation based on the epic's requirements and specifies the type of documentation required (for example, user guide, API, or integration guide), and assigns tickets to respective team members (a technical writer or developer).
4. The PO or PO closes all redundant documentation tickets.
5. The assignee reviews the documentation ticket and begins working on it.

Step 2: Documentation authoring (GitHub)​

1. The assignee creates a branch in the GitHub repository associated with the project.
2. Using a text editor like Visual Studio Code, the assignee writes the documentation in markdown format, uploads images to an S3 bucket, and adds links to the documentation.

Step 3: Collaboration (GitHub)​

1. The assignee commits their changes to the branch, opens a pull request (PR) on GitHub, and, depending on the documentation type and workflow, requests a developer or technical writer review.
2. The PR goes through a review process and the reviewers provide feedback and suggestions.
3. The assignee makes necessary adjustments based on feedback and updates the PR.
4. Once all reviewers approve the PR, it is merged into the master branch.

Step 4: Automated publishing​

1. Automated CI/CD pipelines detect changes to the main branch and trigger a build.
2. The build process generates the static documentation site using Docusaurus.
3. The updated documentation is automatically published on the project's website.

Step 5: Documentation lifecycle management (Jira)​

1. The documentation ticket status is updated in Jira to reflect its progress.
2. Documentation tasks are linked to the corresponding development epic or user story.
3. Any documentation-related issues or updates are tracked in Jira.

Step 6: Iteration and continuous improvement​

1. The team follows an agile approach, iterating on documentation during bi-weekly sprints.
2. Documentation improvements, updates, or new documents are added as needed.
3. End-user and stakeholder feedback is collected during these iterations to ensure that the documentation meets their needs.

By following this workflow, the team seamlessly integrates documentation into the development process, ensuring that documentation is up-to-date, high-quality, and closely aligned with the product's development. This approach enhances collaboration, version control, and overall efficiency in managing documentation projects.

Advantages of the Docs-as-Code adoption​

While Docs-as-Code may not be the best fit for every documentation scenario, it offers several compelling advantages that make it a valuable approach for many teams. Here are some of the key benefits of adopting Docs-as-Code:

Collaboration with developers​

One of the standout advantages of Docs-as-Code is the enhanced collaboration it fosters between technical writers and developers. In complex technical documentation, developers often possess specialized knowledge that can be challenging for non-developers to document accurately. By treating documentation as code and leveraging familiar tools like Git and Markdown, developers can play a more active role in crafting and reviewing documentation. This collaboration ensures that the documentation remains technically accurate and aligned with the codebase.

Continuous delivery​

Docs-as-Code simplifies the process of publishing and updating documentation. With continuous delivery pipelines integrated into a Git repository, authors can commit and push content changes effortlessly. The automated build and publishing process eliminates the need for manual file transfers or complex deployment procedures. This streamlines the publishing workflow, allowing for quick and efficient updates to documentation.

Increased collaboration with contributors​

When documentation teams collaborate within a shared Git repository, they gain better visibility into each other's work. Using Git, authors can easily track changes made by teammates, synchronize their work, and even contribute to each other's content. This collaborative environment promotes knowledge sharing, consistency, and efficient teamwork.

Flexibility and control​

Docs-as-Code tools provide unparalleled flexibility and control over documentation outputs. Authors can customize documentation to match specific requirements, such as URL patterns, layouts, or metadata incorporation. This flexibility is particularly valuable when integrating documentation into websites or other systems with unique needs. Skilled users can harness web technologies like HTML, CSS, JavaScript, and templating languages to achieve complex documentation goals.

Processes as well as tools​

Beyond the tools themselves, Docs-as-Code encourages the adoption of engineering processes for managing documentation. Agile methodologies like Scrum can be applied to documentation projects, enhancing organization and efficiency. By aligning documentation processes with software development practices, teams can improve their workflows and deliver higher-quality documentation.

Handling challenging factors​

Docs-as-Code tools and practices offer solutions for addressing challenging documentation requirements. Localization, content reuse, versioning, authentication, and PDF generation are all areas where Docs-as-Code tools can excel with some creativity and technical expertise. Advanced templating and scripting logic in tools like Liquid, Docusaurus, or Jekyll empower authors to tackle complex tasks effectively.

Conclusion​

In summary, the adoption of Docs-as-Code brings forth numerous advantages, including improved collaboration, streamlined publishing, increased contributor awareness, flexibility, enhanced processes, and the ability to tackle challenging documentation needs. While it may require a learning curve and adaptation, Docs-as-Code offers substantial benefits for teams engaged in technical documentation. By embracing this approach, you empower your team to create, maintain, and deliver documentation that aligns seamlessly with your development efforts, ultimately resulting in better, more accurate, and up-to-date documentation.

In this article, I want to delve deeper into setting up a documentation development process and provide a real example of how to integrate it into your project's development process.

Determining document types​

First, you need to identify all potential document types that your team delivers within your project. You can achieve this by conducting a series of interviews with your team members, including product owners, tech leads, architects, developers, and quality assurance engineers.

Example​

Let's consider an example where the team delivers the following documents: feature overviews, user guides, API documents, migration guides, integration guides, and installation guides. In this case, the documentation can be categorized into two groups:

• User documentation: Feature overviews and user guides.
• Technical documentation: Migration guides, integration guides, installation guides, and API documents.

Determining responsible teams​

Once you have a comprehensive list of required documents, you need to discuss and align which team members will be responsible for writing each type of documentation.

In this scenario, developers are accountable for creating installation and integration guides, while technical writers handle API and migration documents, as well as feature overviews and user guides. Therefore, you have two groups of responsible individuals:

• Technical writers: API documents, migration guides, feature overviews, and user guides.
• Developers: Installation and integration guides.

Setting up a documentation development process​

After identifying the document types and assigning specific teams, you can establish a documentation development process. Your goal here is to analyze each document type and determine the most efficient approach for delivery.

Example​

If an epic introduces a feature that enables Back Office users to create discount vouchers for customers, the best approach might be to test the feature and then write a corresponding user guide. In this case, a technical writer can handle it independently. Conversely, if the epic involves technical documents, such as integration or installation guides that require running multiple commands and incorporating updated code examples, modules, and dependencies, developers should be responsible for these documents.

Consequently, for each document type requiring a distinct documentation process, you need to establish a separate workflow.

Returning to the example from the previous Determining Document Types section, the project encompasses two document groups: technical and user. Each group necessitates its documentation process. In this scenario, a general workflow for each group may look like this:

• Technical documentation: New → In Progress → Dev Review → PO Review → TW Peer Review → Published
• User documentation: New → In Progress → PO Review → TW Peer Review → Published

Exploring and integrating in the development process​

Now that you've established your documentation development process, you need to integrate it into the development process workflow. To do this, you should examine your team's development process workflow in detail and identify the most suitable point for integration. Analyze each step, understand the significance of each workflow status, the responsible parties, and the tasks involved.

Once you have a thorough understanding of the development process, you can determine when documentation tickets should be created. Subsequently, provide the list of requirements to your Jira administrator to automate the generation of documentation tickets for each document type.

Development process example​

Let's consider a scenario where the development process follows this workflow:

New Epic → In Progress → Code Review → Testing → Architectural Review → Demo → Ready for Release → Done

Documentation should be initiated as early as possible to avoid delaying the release. Therefore, the most appropriate time to begin documentation might be when an epic enters the In Progress phase, as this is when all team members start working on their respective tasks. Depending on the document type, the stage at which documentation tickets are picked up and processed may vary, but they should always be ready for the right moment.

When the documentation step is integrated into the development process, it will follow this workflow:

1. When an epic transitions from New to In Progress, documentation tickets are automatically created.
2. The PO or PM decides which documents need to be created or updated based on the epic. They update ticket descriptions to specify the required documentation and close redundant tickets.
3. The technical writer and development teams assign the relevant documentation tickets and follow the documentation development workflows.
4. Once all documentation and development tickets are resolved, the epic can be closed.

Conclusion​

In this article, we've explored the essential steps to establish a documentation development process and seamlessly integrate it into your project's development workflow. By following these guidelines, you can ensure that your technical documentation meets the needs of your project and its stakeholders.

Key takeaways from this discussion include the folliwing points:

1. Determining document types: Begin by identifying all the different types of documents required for your project, ranging from user guides to technical specifications.
2. Determining responsible teams: Assign responsibilities to the appropriate team members based on their expertise. All team members play vital roles in documentation.
3. Setting up a documentation development process: Establish a clear and efficient workflow for creating, reviewing, and publishing documentation tailored to each document type.
4. Exploring and integrating the development process: Seamlessly integrate documentation into your project's development process to ensure documentation aligns with the development timeline.

By implementing these practices, you can streamline your documentation process and improve collaboration among team members, ultimately resulting in high-quality documentation that enhances your project's success.

Remember that documentation is not just an afterthought but an integral part of your project's lifecycle. Starting documentation early and integrating it into your development process will help ensure your project is complete, well-documented, and ready for success.