Overview

All organizations make use of documentation in some shape or form. Engineering teams tend to own and maintain a class of documentation commonly referred to as Tech Docs. Tech Docs refer to artifacts like runbooks, readmes, contributing guides, technical diagrams, etc. While organizations make use of Tech Docs as part of their day-to-day operations, they often struggle in a few consistent areas:

• Discoverability and Search - Documents tend to be kept in a number of different sources (repositories, Confluence, internal wikis) and this lack of consolidation makes it difficult to find exactly the document you’re looking for.
• Completeness - Organizations want to ensure all of their services have the appropriate documentation but its hard to figure out what docs are missing or inform teams what docs they should write when there isn’t a consistent standard for what these documents are.
• Consistency and Standardization - Organizations want to ensure that their tech docs are structured and created in a similar fashion in order to remove guesswork from developers.

To help our customers with this problem, OpsLevel has introduced Tech Docs. Tech Docs is a docs-as-code solution that retrieves documentation from service repositories and displays them in a format that is both easy to read and search. With Tech Docs, the guesswork is taken away from developers. As long as documentation is written as markdown files, OpsLevel will automatically pull them from the repo and display them on the appropriate Service page.

Tech Docs display page

Setting up Tech Docs in OpsLevel

First set up a Git Integration, then map a repository to a service in OpsLevel. OpsLevel will scan the connected repository for Markdown files. If a Markdown file is detected, it will be displayed in the service’s Tech Docs tab.

The file navigation lists all Tech Docs on this service in alphabetical order based on the path. To filter this list, search on the document title or path in the search bar above the navigation.

What’s Supported

Currently Tech Docs supports basic Markdown syntax, including:

• Headings
• Emphasis
• Blockquotes
• Lists
• Code / Syntax Highlighting
• Public and Relative Links
• Images
• We render public images directly in the service’s Tech Docs tab. For image files in relative paths we will render a link to view the image in git.

OpsLevel recognizes files with the following extensions as Markdown files: .md, .mkd, .mdwn, .mdown, .mdtxt, .mdtext, and .markdown

How do I edit my docs?

Use the edit link to navigate directly to the source file on git. Change made in git are automatically synced to OpsLevel, to always display the most up to date documentation on a service.

Pinning Tech Docs

Documents can be prioritized to the top of the Tech Docs sidebar by selecting the pin icon next to the document. Upon selection, these documents will be moved to the top of the order. If a document is unpinned, it is moved back to its original order in the sidebar.

Hiding Tech Docs

Documents can be hidden from the Tech Docs sidebar by selecting the eye icon next to the document.

Upon selection, these documents will be moved to the Hidden tab in the sidebar. Documents can be moved back to the All Docs tab by selecting the crossed out eye icon next to the document.

Note: Hidden Tech Docs will no longer appear in search results.

Searching Tech Docs

Searching across all services

OpsLevel supports searching across the content of all of your tech docs. Enter a keyword in the search bar and the search results page will return a list of tech docs that matched on the file name, path, or content. The search algorithm determines the best match ranking order and presents the most relevant item at the top of the list.

Searching on a single service

To search on a specific service, navigate to Service's Tech Docs tab. Enter a search term using the the search bar above the navigation. The file list will be filtered down based on document title or path matches.