Knowledge Base - Article Writing Guidelines

General Guidelines

  1. KB articles should feature original content as much as possible. Do not copy-paste documents that already exist in other sources, such as software help files. If you feel it is important to have an article that deals with a topic that is already addressed in a help file, introduce the subject with one or two paragraphs, followed by “For more information, please see [include a link to the original source]” Articles that only contain a link to another source without any introduction or explanation are not permitted.
     
  2. If you are including extended direct quotes from other sources, you must ensure that you are not violating any copyright laws. While it is permissible to reference existing content in your article, you should never simply copy-paste other people’s work and try to publish it as your own article.
     
  3. Unfinished articles or “placeholders” cannot be published. The use of “work in progress” phrase is not permitted in any articles submitted for publishing. You can save an unfinished article without submitting it, and come back to it later.
     
  4. Articles that are ready to be published, should be saved with “Status” field set to “Submitted.” Articles that are drafts and work in progress, should be saved with “Status” field set to “Not Submitted.”
     
  5. Avoid using technical acronyms without providing their full equivalent first. For example, when you want to mention IMAP protocol, on the first use within your article say “Internet Mail Access Protocol (IMAP).” Subsequently, you can just say “IMAP.”
     
  6. Maintain consistency of spelling. For example, avoid spelling "email" in one part of your article and "e-mail" in another.
     
  7. Use only one space following a period to separate sentences. The use of two spaces is meant only for printed materials.

Categories

  1. Each article must be assigned to a category. Note that in TeamDynamix it is not possible to assign an article to more than one category, however, you can add shortcuts to your article in other categories.
     
  2. Do not create new categories. If you feel that a new category may be needed, please contact KB Administrator to discuss.

Article Title (Subject)

  1. Use a single sentence that is complete with proper punctuation.
     
  2. Titles should be as meaningful as possible.
     
  3. Capitalise first letter of each word.
     
  4. Single word or single phrase titles are not permitted. You need to provide more context.  For example, instead “Installation instructions” use "Installation Instructions for Adobe Acrobat."
     
  5. It is OK to have the title in the form of a question. Example: “How to Install Adobe Acrobat on a Macintosh Workstation”
     
  6. For frequently asked questions (FAQs) articles, start the title with "FAQ: <title>"
     
  7. If you are documenting a known issue, include a prefix: "Known issue: <title>"

Article Summary (in Settings section)

  1. Do not leave blank.
     
  2. Do not repeat the tile/subject in here.
     
  3. Provide at least one full sentence, preferably one paragraph that summarises the contents of the article (i.e. executive summary). This could be the same an opening paragraph in the article body.

Article Body

  1. Do not include article title in the article body. The title you specified in the Settings section will automatically appear on top of the page when you put the article in read mode.
     
  2. Start your article with an opening paragraph that introduces topic of your article to the audience. It is OK to say something like "This article discusses recommended method for installing Adobe Acrobat you macOS workstation."
     
  3. For log articles with many sections, use anchor links and include table of contents in the opening paragraph.

Formatting

  1. If copying and pasting from another source, paste as plain text to strip external formatting, then reformat your article using formatting tools in TeamDynamix.

     
  2. Use “Heading 2” and “Heading 3” tags for your section titles. Do not use “Heading 1” which is reserved for the article title, and do not bold or italicise section titles.
     
  3. All links to external sources (i.e. other than other KB articles) should open in a new window.
     
  4. Use bold font to indicate clickable items.

    Example: "Select Open from the File pull-down menu."

Article Settings

  1. If you are writing an article on behalf of another person, please list that person in the “Author” field.
     
  2. Always check the box next to “Notify Owner on Feedback”
     
  3. Always enter at least one tag in the “Search tags” field. Use keywords as search tags.
     

Related Articles

  1. Each KB articles should include links to related content. Do not provide more than 5-10 links per article.

Standard Tags

Tags are not the same as "search keywords." You should not use keywords from your article as tags because the search engine will find those keywords even if they are in the body of the article and not spelled out as tags.

Tags is an alternative way to categorise KB articles. Do not use categories already used in Services / Knowledge Base pages as tags.

Use on of the following tags for each article to indicate who the target audience is.

  • audience-internal
  • audience-client

Use on of the following tags for each article to indicate type of the article.

  • type-informational
  • type-howto
  • type-troubleshooting
  • type-faq
  • type-other

 

Print Article