Help desk documentation: Best practices for DevOps teams

Modern help desk functions

Help desks are the first point of contact between a user and an organization's resources. In most cases, help desks offer support for the infrastructure, endpoints and applications a business provides to its clientele. There are three main types of help desks:

• IT support help desks are inward facing and assist an organization's employees with a wide range of hardware and software issues. Examples include password resets, use of company resources -- such as printers, laptops and other assigned endpoint devices -- and complex tasks such as resolving network problems.
• Customer service help desks typically support external users, such as business partners, in using a product or service paid for by the customer -- for example, a subscription-based SaaS offering. This limits the scope of the assistance that customer service desks can provide.
• Business service help desks are another internal resource that provide business-specific services to employees and are operated by a non-IT team, such as finance, HR, legal or sales. For example, HR help desks offer employees guidance for benefit and payroll elections, while finance help desks might assist with issues involving expense reports or accounts payable.

Help desks can provide a mix of human interaction, automated responses, and access to tools and documentation -- but there aren't guidelines that define or require any of these components. Consequently, every help desk setup is different, offering a unique mix of resources tailored to the needs of its organization and users.

Some help desks allow round-the-clock access to tools, documentation and a searchable knowledge base, but restrict human assistance services via chat, email and phone to regular business hours. Another type of help desk, commonly known as a self-service desk, concentrates exclusively on documentation and knowledge resources.

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

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

Documentation access and management

A key part of any help desk is documentation. Up-to-date, well-prepared documentation is a time- and cost-effective resource that answers a vast array of questions for users at any time. Even businesses with little or no live help desk staffing can provide user assistance through comprehensive, searchable documentation. A typical help desk includes four major product or service documentation categories: documents, knowledge articles, videos and forums.

A comprehensive help desk can also include resources beyond documentation:

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

Help desks vs. service desks

Help desks are primarily responsible for handling IT-related incidents, such as troubleshooting and bug fixes. Service desks, in contrast, provide support and guidance for more routine or less acute issues and user requests. For example, a service desk might assign endpoint devices, such as laptops, and create SaaS accounts during employee onboarding. Service desks are often viewed as "help desk lite" or as a subset of help desks.

In practice, help desk and service desk are sometimes used interchangeably. Although experts might debate the technical accuracy of this use, the difference between the two is often a matter of interpretation, as there are no clear or broadly adopted requirements for help or service desks. The definitions, components and capabilities of support resources vary greatly across organizations.

While service desks might offer the same types of documentation available through a help desk, their noncritical nature often leads to an emphasis on how-to and self-service content. For example, a service desk might offer guides or videos on how to use 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's a crucial part of any software release. Commits and sprints happen fast, but DevOps teams should always take the time to document changes and additions to upcoming versions.

There are no standards or requirements for documentation tools -- DevOps teams can use anything from Microsoft Word to wikis to create suitable documents for a new build. However, some commonly used tools can accelerate 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)
• Bit.ai (document collaboration platform)
• Nuclino (collaboration and documentation platform)
• Whatfix (walk-through 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 generator)
• Read the Docs (software documentation)

Managing DevOps documentation

Documentation has a shelf life -- it demands regular attention and management from help and service desk teams. The collaboration efforts common to DevOps often include help and service desk teams that can offer insights into the availability and quality of existing documentation.

Documentation management efforts could include the following:

• Formalize the documentation and knowledge management processes. This can include setting standards for document structure and content, and regularly reviewing documentation to ensure its timeliness and accuracy.
• Make documentation searchable. It's easier to find relevant documents on documentation platforms that filter results by tags, labels, types, keywords or other criteria. Adding creation dates or other time-related designations can expedite the process of checking whether documentation is up to date.
• Gather user feedback. Grading documentation with a user rating system helps organizations identify and prioritize the most relevant and helpful documents -- and deprioritize 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 arrive rapidly -- sometimes daily. But software product adoption can hinge on solid documentation, which makes it essential for DevOps teams to create accurate, complete and up-to-date documentation.