E-Handbook: Combat these common DevOps challenges and mistakes Article 3 of 4

kentoh - Fotolia

This article is part of our Essential Guide: How to create a successful DevOps organizational structure

How DevOps teams use a CMS for documentation, collaboration

DevOps teams should choose a CMS that enables continuous, integrated content management, and select tools for internal document sharing that build an easily searched and categorized knowledge base.

DevOps teams generate a lot of content in pursuit of CI/CD code production: customer documentation, meeting notes, architecture documents and other project artifacts. Teams should also be able to access this knowledge base quickly to troubleshoot issues and maintain delivery cycle velocity.

To integrate all this information into a CI/CD toolchain, select a content management system (CMS) that offers an API to plug into other tools. DevOps staff should consider requirements for customer-facing and internal content, rather than simply accept the enterprise's standard CMS choice.

Options for external content management

CI/CD tools render traditional database-driven CMS models too slow and redundant for content publishing required by GitHub, Chef, Selenium and other documentation-generating pipeline components.

A Git-based CMS for documentation suits the demands of customer-facing content in a DevOps environment. Git-based offerings perform and scale better than SQL-based CMSes. They rely on a decoupled architecture, with several microservices for content authoring and delivery that run in distinct subsystems. For security and scalability benefits, install the CMS in the same cloud that hosts the DevOps team's other CI/CD tools.

DevOps-tailored CMS options for project management and documentation rely on various models of operation.

Crafter, an open source Git-based CMS, separates content and code updates, which, the toolmaker posits, enables code delivery velocity. Content creators can make updates continuously and update information via Git, unaffected by software pushes that go through the CI/CD pipeline. A Git push moves development forward from an isolated code branch through testing and into production automatically. A Git pull boots up new environments with any appropriate version of related content.

Another approach is based on the operation of a content engine. Accion Labs, a consulting and staffing firm that supports development and project delivery, separates content management from the application, just like the Git-based approach. The company combines a NoSQL database; HTML5, CSS3 and JavaScript languages; and a cloud service provider's content delivery network to manage DevOps documentation and other content. Accion Labs asserts that database-driven CMS products, such as Drupal and WordPress, pose security risks because of management overhead.

Seek CMS technologies for externally geared documentation that publish content through multiple digital channels, such as enterprise sites, mobile apps, microsites and any other place in which your customers access information. Evaluate tools that require more or less experience on Git, depending on the skills of content authors.

CMS requirements for internal content

For internal content used by the DevOps team, keep content management simple, searchable and auditable. One approach is to centralize content in a wiki or cloud repository with versioning, alerting, tagging and search. While some businesses expect DevOps teams to use an already-established CMS for documentation and knowledge sharing, ensure that the technology checks all of the boxes, and push back if it doesn't. Invest time to tune the platform's search engine, set up tags and create alerts on documents or pages so that the appropriate team members know when they're updated.

Consider a different content management approach for internal documentation that revolves around collaboration rather than publishing routes.

Atlassian Confluence offers a simple authoring process and integration options to manage internal team documentation. Users can also access a library of add-ins to customize workspaces with reporting, external content and navigation. They can also create reusable templates for workspaces in the development organization to use as new projects kick off.

Another method uses a cloud repository for content management, as evidenced in offerings from Dropbox and Box. For example, Dropbox -- and, by extension, the document design of Dropbox Paper -- offers lightweight content authoring and file storage to act as a CMS for documentation. It integrates with other tools in the DevOps toolchain through an API. These types of products typically include search features and the ability to invite collaborators to documents. Build security for this class of collaboration tools via the organization's identity access management setup or single sign-on.

Content management options for DevOps teams multiply as APIs become standard features for tool integration. However, successful document management depends on planning: Make content management part of the CI/CD toolchain and a line item in the DevOps tools budget upfront, and don't settle for the established corporate CMS platform if it doesn't meet the software team's needs.

Next Steps

How to approach and instate automated IT documentation

Dig Deeper on Systems automation and orchestration

Software Quality
App Architecture
Cloud Computing
Data Center