How do you make your technical documentation easy to find?

As well as standard naming conventions, if the documentation set is intended for use by others then an indexing system is always helpful, how else do you know what’s already there?!

The best practices for titles are: - Establish a naming convention based on 2-3 key variables. This could consist of a client name, software/hardware name, issue type, or anything to clearly organize documents. - Keep folders that are named based on the established convention so things are easy to index and you know where each new doc goes. - Make sure everyone creating documents has a clear understanding of the naming convention and how folders are structured so things don’t get misplaced do to lack of clear communication.

Titles and documentation should of cohesive and easy readability for internal team members. - Proper organization methods should be taken into consideration when formatting KB articles. - These documents should be written with the end user in mind. All team members with KB writing access should follow a similar format/standard

When it comes to titles, my approach is always using specific and repeated terms to describe a specific document based on the info it provides. For example, if a document is about doing some thing where the variables are known and the outcome is always the same, it should start with “How to…”. If a document is describing possible variables based on troubleshooting it would start with “Troubleshooting” or “KB” for Knowledge Base about the particular subject. Depending on the documentation system used this can offer at a glance way to distinguish one document from another .

The one thing I have learned about documentation is that it always needs to be written as if you have never solved the problem before. And if it applies to the solution, should also include steps on how to do any additional tasks, or reference an article that then goes into further detail about that additional task. I’m a huge fan of screenshots, partnered with arrows or circles. A lot of people tend to write articles as if it is a given that the person reading it will know how to read between the lines. I disagree. I think every article should be written as if that person knows nothing about anything involved in solving that issue. Sort of a how to for dummies approach. No detail is too small.

Good signposting with headings is very important. Each heading should accurately summarise what the section or paragraph beneath it is describing. The headings should have consistent tenses, e.g., starting with an imperative verb. As a rule of thumb, a heading should be about 4 words maximum.

I am a firm believer in using a KB to it’s full potential. Articles should be written in a standard format, and be clean and concise, but contain all steps required to achieve the goal. There is a training cost reduction with this method too. A good test of a KB article is to hand a task over to an inexperienced analyst, and ask them to walk you through what they would do based upon the document. That way you can also see if there’s anything you have missed or which needs to be changed.

Agreed. How you would approach documentation as an end user should always be kept in mind that is how you can keep it well-structured and easier to navigate for the user

When it comes to findability, marketing probably has the oldest expert in the field. Thus, SEO tips usually apply to internal enterprise search solutions as well. Moreover, if your content is at least partially available to the general public, I suggest treating your content as a real marketing asset. I've seen several instances where technical documentation articles did better at SEO than marketing blogs. Here's my 5 cents: work with your marketing team to identify the most strategic topic pages that could be improved - with clear structure, descriptions, illustrations, and keyword tagging.

Tags and keywords are one of the best ways to find data. No matter how well titled and organised your knowledge base is, over time kb bulk begins to obscure where to find what you need. Get a good tool to store your knowledge. Good tagging and a good built in search function - particularly with a structured query language for advanced users makes good knowledge findable. A Rest API is a nice bonus.

Keywords and tags are also a great way after articles are published to have that simple way to search for them. I’m a big fan of using tags, especially in something even in my Evernote database. Having one, two, or even three words that sum up what the articles related to helps out a lot when you’re not exactly sure what the article was named at a later date.

This is some thing which a lot of organizations have a hard time with, especially if they do not have a turnover of staff. Folks become very familiar with “how we do it now” but then they leave the article untouched. I constantly update screenshots, screen prompts, and anything that the person will see or have to perform while doing the same task. The best time to do this is when you yourself are doing the task a new way for the first time. It may take you longer because you’re recording your steps while you’re performing the procedure. But in the long run, everyone after you will benefit from this time spent. The articles well, then be published with a new more recent date, which also helps find things much easier.

I recently become a huge fan of ITGlue. It’s a cloud-based documentation system mainly used for Technology. However could actually be applied to different industries as well. The security in the access is very granular. So different people can have access to different sections based on responsibilities and jobs. For example, system administrator passwords can be stored in the same place as other less critical passwords however, only certain individuals will have access to those passwords versus the other passwords that are more commonly used for general support.

There is a cost argument to KB’s too. If you invest the time to create a well polished KB document on the first instance of the issue. There is no doubt that that scenario will occur again. As you now have an article, the resolution time is reduced and the fix is delivered quicker to the customer. Over multiple times this also has a massive cost saving to the business. Some Service Desk systems allow KB articles to be used in self-service, driving fixes to as close to the customer as possible. It’s prudent for any customer facing documents to be reviewed for fact and compliance before they are published

Leverage tools that you already have like Office 365 SharePoint. SharePoint is literally designed to share data inside an organization. When I get a new client, I create a SharePoint site, Team and Mailbox for that client. I also create a OneNote Notebook for taking notes and in general keeping track of ideas. All communication, documents and service reports are stored in SharePoint and accessible. OneNote has a general template that is used for each client. Official tech "documents" are stored on a wiki that is used for client and tech support information.