Writing good short descriptions for knowledge base articles


Explanation

Keep it short

Try to keep the short description (title) of a knowledge base article as short as you can. This allows your audience to easily read the short description when skimming through search results. For example, the short description "How to: Set up a new TTUnet VPN connection within Android" can be shortened to "How to: Set up TTUnet VPN in Android" without losing necessary information.

For incident articles, provide the cause and/or solution in the short description

For incident articles (error/problem), after stating the error message or the symptoms of the problem in your short description, indicate the cause and/or the fix in the short description whenever possible. For instance, the short description "Problems when signing in to TechMail because eRaider password is expired" is better than "Problems when signing in to TechMail" because the audience doesn't even have to open the article to know the fix. Astute audience members will grasp the answer immediately in these cases, saving them some effort.

No categorization in short description

There is no need to restate the category in the "Short description" field. We have a category field for that purpose. The article's short description serves a different purpose—summarizing the entire article.

No questions

Do not state a short description in the form of a question unless absolutely necessary.

Changing short descriptions

If you need to change an existing article's short description:

  1. Obtain the number of the article that you wish to edit.
  2. Go to the knowledge base and search for the number of the article.
  3. The results will display the article with that number plus any articles that are linked to that article. Review each article which is linked to the article for which you wish to change the short description. If the short description of your article is referenced in any of these articles, edit them and change the short description to the new short description of your main article.
  4. Finally, edit the main article (the one on which you wish to change the short description). Change the short description and save it.

Example short description formats

Mobile

If the KB article would work on the recent versions of a mobile operating system, keep it simple and list only the name of the platform without a version.

EXAMPLE: How to: Connect to TTUnet Wi-Fi in Android

macOS

If the article would work on all of the versions of macOS for which we maintain content, just put "on your Mac" instead of the software versions.

EXAMPLE: How to: Connect to TTUnet Wi-Fi on your Mac

If there is a need for different instructions for the versions of macOS for which we maintain content, specify them. There is no need for version numbers unless the article is specific to a particular sub-release (e.g., 13.2.1)

EXAMPLE: Unable to resize APFS disk images in macOS 13.2.1

Windows

If the article would work on all the versions of Windows for which we maintain content, just put "in Windows" instead of the software versions.

EXAMPLE: How to: Access Task Manager in Windows

If there is a need for different instructions for the versions of Windows for which we maintain content, we would create separate articles. In the short description, specify the version of Windows for which the article is applicable. Also, there is no need to type "Windows" each time.

EXAMPLE: How to: Create a local user account in Windows 11 or 10