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 wireless connection within Android" can be shortened to "How to: Set up TTUnet Wi-Fi 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:
- Obtain the number of the article that you wish to edit.
- Go to the knowledge base and search for the number of the article.
- 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.
- 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 (for instance, 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