Best practices for DevOps teams


Documentation and knowledge resources save organizations money, improve customer satisfaction, and increase product adoption and loyalty. With proper documentation, help desks can provide fast and consistent customer support and allow users to extend their capabilities with a software product.

But despite its importance, documentation can be problematic for DevOps projects. Iterative development paradigms result in frequent changes and updates, and translating them into timely documentation requires constant attention to detail to avoid introducing errors and knowledge gaps. DevOps teams should adopt the practices and tools necessary to provide complete and up-to-date software documentation to the help desk.

Modern support functions

Help desks are the first point of contact between a user and an organization’s resources. In most cases, help desks provide support for the infrastructure, endpoints, and applications that a company provides to its customers. There are three main types of support centers:

  • Computer Help Centers are inward looking and helping organizations employees with a wide range of hardware and software issues. Examples include password resets, use of corporate resources – such as printers, laptops, and other affected endpoint devices – and complex tasks such as troubleshooting network.
  • Customer Service Help Desks typically support external users, such as business partners, in the use of a customer-paid product or service – for example, a subscription-based SaaS offering. This limits the scope of assistance that customer service desks can provide.
  • Business Support Centers are another internal resource that provides company-specific services to employees and are managed by a non-IT team, such as finance, HR, legal, or sales. For example, HR helpdesks offer employees advice on benefits and payroll choices, while financial helpdesks can help resolve issues with expense reports or accounts payable.

Help desks can provide a mix of human interaction, automated responses, and access to tools and documentation, but there are no guidelines defining or requiring any of these components. As a result, each help desk setup is different, offering a unique mix of resources tailored to the needs of its organization and its users.

Some help desks allow round-the-clock access to tools, documentation, and a searchable knowledge base, but limit human chat, email, and phone support services to normal business hours. Another type of help desk, commonly referred to as a self-service desk, focuses exclusively on documentation and knowledge resources.

Regardless of its type and resources, a help desk generally fulfills the following four main functions:

  1. Establish a common or single point of contact.
  2. Answer questions or solve problems.
  3. Win time and money.
  4. Improve user experience or improve user satisfaction.

Access and management of documentation

Documentation is a key part of any support service. Up-to-date and well-prepared documentation is a quick and economical resource that answers a wide range of questions for users at any time. Even companies with little or no live support staff can provide user support with comprehensive, searchable documentation. A typical help desk includes four broad categories of product or service documentation: documents, knowledge articles, videos, and forums.

A comprehensive support service can also include resources beyond documentation:

  • downloadable tools for testing and diagnosing potential problems;
  • access to relevant software patches and updates;
  • human assistance via chat, email, telephone or collaboration tools such as Zoom and Microsoft Teams; and
  • metrics on support success and user satisfaction.

Help Centers vs Service Centers

Help desks are primarily responsible for handling IT-related incidents, such as troubleshooting and bug fixes. Service centers, on the other hand, provide support and advice for more common or less acute problems and user requests. For example, a service desk can assign devices, such as laptops, and create SaaS accounts when onboarding employees. Support services are often referred to as “lightweight support services” or a subset of support services.

In practice, help desk and service desk are sometimes used interchangeably. Although experts can debate the technical correctness of this usage, the difference between the two is often a matter of interpretation, as there are no clear or widely adopted requirements for help desks or service. The definitions, components, and capabilities of support resources vary widely from organization to organization.

Although service desks may offer the same types of documentation available through a help desk, their non-critical nature often leads to an emphasis on practical, self-service content. For example, a service desk might offer guides or videos on using DevOps or third-party applications that the service desk has configured for the user.

Tools for DevOps Documentation

Although documentation is rarely included in the DevOps cycle, it is a crucial part of any software release. Commitments and sprints are quick, but DevOps teams should always take the time to document changes and additions to upcoming releases.

There are no standards or requirements for documentation tools – DevOps teams can use anything from Microsoft Word to wikis to create appropriate documents for a new release. However, some commonly used tools can speed up and automate parts of the documentation process:

  • Apiary (API development and documentation)
  • APIMatic (API documentation)
  • Readme (API documentation)
  • Stoplight (API design and documentation)
  • SwaggerHub (API design and documentation)
  • ProProfs (knowledge base)
  • Tettra (knowledge base)
  • KnowAll (WordPress knowledge base theme)
  • Document360 (self-service knowledge base)
  • iA Writer (text editor and knowledge base)
  • Dropbox paper (wiki)
  • (documentary collaboration platform)
  • Nuclino (collaboration and documentation platform)
  • Whatfix (Presentation and Guide Creator)
  • Typora (Markdown editor)
  • SimpleMDE (Markdown editor)
  • MarkdownPad (Markdown editor)
  • ClickHelp (software documentation)
  • Doxygen (code documentation generator)
  • Sphinx (code documentation generator)
  • GitHub Pages (website builder)
  • Read the Docs (software documentation)

DevOps documentation management

Documentation has a lifespan – it requires regular attention and management from support and service teams. Common DevOps collaborative efforts often include support and service teams who can offer insight into the availability and quality of existing documentation.

Documentation management efforts could include the following:

  • Formalize documentation and knowledge management processes. This may include establishing standards for document structure and content, and regularly reviewing documentation to ensure currency and accuracy.
  • Make documentation searchable. It is easier to find relevant documents on documentation platforms that filter results by tags, labels, types, keywords or other criteria. Adding dates of creation or other time-related designations can speed up the process of checking documentation for updates.
  • Collect user feedback. Scoring documentation with a user rating system helps organizations identify and prioritize the most relevant and useful documents, and downgrade those that are less meaningful to users.

Documentation lifecycles are notoriously short in busy DevOps environments. This is especially true early in product development, when software changes and additions happen quickly, sometimes daily. But adoption of a software product can depend on solid documentation, making it essential for DevOps teams to create accurate, complete, and up-to-date documentation.


About Author

Comments are closed.