DevOps and DevSecOps require agile documentation practices to deliver quality documentation on time with an iterative software delivery cycle. It's a similar journey to DevOps with a move to automation and a more agile approach to content. If documentation is only now entering your organization's DevOps discussions, it's time to catch your documentation practices up to DevOps.
Here are the four levels of DevOps documentation maturity:
Level 1: Ad hoc and siloed
In the first level of DevOps documentation maturity (most immature), documentation efforts do not align with DevOps efforts. DevOps development follows their path while the documentation team follows a separate path, which often causes the documentation to be behind the development. Delaying a product launch because of documentation is not an option in the hyper-competitive cloud world.
Staffing
The documentation staffing at this level hasn't deviated from the old way of doing things. Technical writers still work in a centralized team detached from the development teams. A gulf between the technical writing group and development teams happens for a variety of reasons, including:
- Corporate politics that create team divisions and silos
- The team sees technical documentation as a checkmark, not an asset that creates project success
- The hiring of technical writers in an afterthought
- Misalignment of technical writer priorities with development team realities
Another sign of staffing challenges at this phase is the "definition of done." This is where technical writers new to the agile experience may find it challenging working with applications developed through the iteration that continuous integration/continuous development (CI/CD) toolchains and processes.
Documentation tools and processes
Technical writers in this phase use tools they're used to from traditional office work, such as office suites and layout programs. The tools aren't agile and require version control, and content management requirements don't integrate efficiently with DevOps toolchains or support development velocity. Technical writers still follow legacy templates and processes at this level.
Outcomes
The documentation deliverables at this level may not be current or even lack technical accuracy. When a development team moves at the velocity of DevOps and their technical writer support follows a legacy non-agile process (using proprietary tools and delivery formats), it is difficult to iterate the documentation and keep pace with application changes.
Level 2: Experimentation and pilot
The second level of DevOps documentation maturity (experimentation phase) is where DevOps leads and technical writers make the first moves to implement more agile documentation practices and tools.
Ideally, experimentation is part of a pilot project with support from stakeholders who have the most to gain from improved documentation delivery and its integration with DevOps practices.
Staffing
The staffing at the experimental phase can take one of three forms:
- A forward-thinking technical writer experimenting with more agile tools on their own time brings their findings to work because they want a better way to do their job. The writer pitches the idea of a more agile documentation process to their leadership.
- The DevOps lead or engineer is experimenting with tools such as Hugo and Jekyll and integrating the tool into the CI/CD pipeline. The DevOps team teaches the tooling to the technical writer.
- The team brings in third-party contractors or consultants with expertise in DevOps documentation tools and knowledge of where documentation tools fit into the CI/CD toolchain and DevOps lifecycle.
Documentation tools & practices
Hugo and Jekyll are among the tools that appear during this phase. This phase also sees new approaches to content strategy and technical writing.
Outcomes
An outcome of a successful experimentation phase should be "land and expand" and set up DevOps documentation practices that other project teams can put into practice.
Experimentation in this phase also includes fundamental changes to content strategy and publishing processes, which technical writers outside the pilot project can learn and adopt.
A change in technical writer hiring practices is another potential outcome of this phase based on the pilot's success. It's essential to bring your in-house writers along by offering them training about DevOps and your newly implemented documentation tools.
New documentation tooling and processes are the critical outcomes for this phase. You'll also need to sell this outcome to your leadership, stakeholders, and other teams through presentations, status reports, and internal case studies.
Level 3: Partial automation and expansion
The third level of DevOps documentation maturity (partial automation and expansion) is the next step in the "land and expand" outcome. In this phase, other DevOps teams adopt the DevOps documentation tools, practices, and lessons learned from the pilot project.
Staffing
Technical writers and DevOps teams begin a much closer collaboration at this level. Hiring new technical writers at this level focuses on writers with experience in DevOps environments.
Tools and documentation practices
Technical writers begin to migrate away from their legacy tools and processes and adopt more agile documentation tools during this phase, such as:
- docToolchain
- Docbook
- Hugo
- Jekyll
Technical writers also work to adjust their legacy practices at this level.
Outcomes
DevOps documentation tools and practices expand beyond the pilot project(s) to become standard practices. Continuous learning is essential at this level as new teams go live with new documentation tools and processes.
Level 4: Full adoption
The highest level of DevOps documentation maturity (full adoption and automation) is where the tools, practices, and processes are in place to support documentation as a top-level project priority. Reaching this level of maturity requires experimentation, iteration, and collaboration.
Staffing
Full automation brings together the closest collaboration between the DevOps team and technical writers. A mark of this phase is that your technical writers become firmly embedded into the project team's workflow. Large enterprises with engineers assigned to maintain DevOps toolchains assume maintenance duties over the documentation tools.
Documentation tools and practices
Technical writers at this level of maturity are standardized on markdown language and automated tools.
Outcomes
The outcomes at this phase are a complete suite of tools and practices that support the automation of online documentation publishing. Technical writers can publish and republish documentation as needed to support an iterative development process.
Continuous learning is another outcome of this phase. Technical writers and toolchain maintainers seek ways to improve automation and processes that help documentation practices.
Final thoughts
DevOps documentation requires a similar journey as you went through to reach DevOps or DevSecOps maturity. I hope to reach a point across industries where moving to more agile documentation practices and tools becomes part of an organization's overall DevOps journey. There is still work to be done. Advancing your DevOps documentation maturity should come as part of your overall DevOps maturity or even DevOps to DevSecOps transformation.
Comments are closed.