No software project is complete without documentation such as user guides, examples, references and change lists. Documentation shows users how to adopt, deploy and use any given software. Without proper documentation, potential users might overlook or abandon even the most powerful and dynamic software products.
But the pace of software development is increasing. Each new iteration brings changes, fixes and new features that demand careful documentation. As software development cycles accelerate, the need for accurate and complete documentation throughout the DevOps lifecycle is more important than ever.
However, the traditional long-tail approaches to technical documentation can't keep pace with technology. As more businesses embrace and expand the adoption of DevOps and other Agile development paradigms, businesses and development teams should revisit and update the ways IT departments prepare and maintain documentation.
Traditional documentation problems
Useful and effective documentation exhibits three principal characteristics:
complete
accurate
clear
To understand the effect of Agile development on software documentation, it's important to recognize how the dynamic changes and organized chaos of Agile development affects all three of these documentation characteristics.
When traditional documentation was adopted for Waterfall-type development approaches, writers came in typically at the final stages of the project before its release. Writers took designs, data and details from designers and developers who had finished -- or nearly finished -- the project. Writers then converted those notes, diagrams, charts, menus, descriptions and details into finished and polished documentation, which was shipped with the finished project that took months, or even years, to complete. Thus, the documentation phase was often a singular effort that reflected a finished product.
An Agile project might deploy initial iterations after just weeks or days of development. The initial iteration was followed with subsequent releases to fix bugs, add features, and make other functionality and performance changes. Each subsequent iteration can appear in just a matter of days -- or less. Every release and its changes must be adequately documented to support users, developers, operations staff and business leaders.
Thus, the demands of DevOps development place enormous pressure on technical writers to deliver and maintain quality documentation throughout the project's lifecycle. The time pressure of DevOps release schedules can translate into substandard documentation that doesn't meet the qualities listed above. Some of the pitfalls include the following:
Writers in a rush to complete documentation might overlook features -- especially secondary or supporting features. If a feature or capability isn't described appropriately, users won't know it's there or how to use it.
Descriptions might include incorrect information, such as errors in coding examples or incorrect illustrations of syntax or arguments. Details like file paths or variable names might be wrong. And common workflows might be described incorrectly.
Descriptions and examples might be difficult to understand. A lack of suitable editing processes enables spelling and punctuation flaws to obfuscate the meaning of important instructions and descriptions.
These resulting documentation problems can slow adoption of a new release or generate unnecessary help desk tickets as admins attempt to fill any knowledge gaps left by poor or missing documentation.
How to approach documentation in DevOps
Businesses and software teams must reconsider how that project documentation is created and maintained to keep documentation in step with DevOps and other Agile development paradigms.
Make these four fundamental changes to manage DevOps documentation.
1. Document early and often.
While traditional documentation was often treated as an afterthought or as the final polish on the project, DevOps documentation -- and, intrinsically, its writers -- must come into the development process or workflow from the start of each iteration. This enables writers to document -- while the build and testing is in progress -- the current build, including its features, examples, references, case studies and other how-to details.
Each subsequent iteration must revisit existing documentation to make changes and updates, as well as add new content to reflect the latest build. In short, documentation should hold the same project value as coding and testing.
Modern technical writers cannot be simple wordsmiths.
2. Expect more tech savvy.
Modern technical writers cannot be simple wordsmiths. Maintaining documentation in a DevOps environment requires too much speed and agility to rely on the notes of architects and engineers.
Today's technical writers must take some ownership of the project and learn its inner workings hands-on. The scope of knowledge might include programming knowledge, such as writing API examples; workflow knowledge to outline key how-to steps; and some architectural knowledge to describe how the product works. Current hiring trends include increased technical expectations for dedicated writers.
3. Tap technical staff for help.
When dedicated writers are available on staff, bolster opportunities to communicate and collaborate with writers and developers. When dedicated technical writers are not available, senior developers and project managers might expand their role as technical writers to tackle at least some documentation requirements. There might be several individuals involved in the overall documentation effort, each handling a part of the overall documentation package.
4. Use alternative media.
Time matters. Businesses realize that traditional long-form types of documentation -- such as extensive user manual PDFs -- are inappropriate, or even impossible, for an Agile development environment. Businesses turn increasingly to more flexible and searchable documentation platforms that are easier to create and maintain, such as wikis. Some documentation platforms include automation to update documentation as code or features change.
Best practices for documentation in DevOps
Once businesses enact changes to accelerate suitable documentation for DevOps software projects, there are at least five best practices that improve documentation outcomes:
Eliminate silos. Writers -- or other staff tasked with documentation preparation -- should be included as a normal and essential element of every development team. They should work alongside developers as standard team members. Just as a business with multiple concurrent projects can share developers and testers, writers can also transition across team and project lines to help with multiple projects.
Collaborate.Communication and collaboration are not buzzwords in Agile environments -- they're a founding principle. Writers need ready access to notes and free communication with developers and other stakeholders as needed to develop the necessary documentation. This could involve regular team meetings or participation in testing and validation processes, for example. The more that writers know about a product and how it works, the better they can document it.
Set documentation requirements. Every software project is different and imposes different documentation demands on development teams and writers. Part of a project's requirements should include an outline of documentation requirements, such as references, examples, use cases, user stories and how-to guides. Establishing the documentation upfront makes it easier for writers to meet goals and focus on the most important types of documentation.
Adopt standard tools. From Microsoft Word to wikis, there are countless tools and platforms that help writers build and maintain documentation. Although the actual tools used for DevOps documentation depend on the business's and project's needs, standardize on a specific set of tools that all writers should use. Familiarity with these specific tools can make the work faster and more efficient.
Automate tools where possible. Some documentation tools, such as wikis, have features that automate some aspects of the documentation process. For example, adding a new call to an API triggers an automatic addition of that call to the section of documentation covering references and examples. This ensures that writers flesh out the additions and account for all changes and new content. When automation is adopted, document the automation features and dependencies so that others can continue to update the tools over time.
There's no single solution
There is no standard approach to DevOps or other Agile project documentation. Early attempts to standardize documentation, such as open source DocOps, never took hold because of the many exceptions and needs of software documentation. Documentation goals and content requirements vary dramatically depending on the type of software project, the project's scope, the nature of the business and the demands of users.
For example, the documentation produced for a mobile game differs greatly from an industrial software platform's documentation. Writers still add quality and value to a software project -- as long as they're able to keep pace and handle the challenges of Agile environments.
