This article provides some authoring guidelines for writing articles for the Known Error and Support and Troubleshooting knowledge bases.
General Writing Guidelines
-
Titles: Phrase the title using terms for which customers are likely to search (the symptom) rather than the underlying technical problem. Try to be specific.
For example, instead of "Changes to action_body.xml break some UI action client scripts," try saying "Periods in UI action names cause 'Unexpected token' error." For more information and examples, see the article Article Title Guidelines (KCS).
-
Make Public articles generic for all users.
-
Do not include specific customer information like instance names or user names in the text or in URLs or screenshots.
-
Avoid referring to "the customer" or "the user" (use "you" or rephrase) and avoid the use of first-person ("I" or "we").
-
Do not include internal information when documenting fix attempts or investigations.
-
-
When providing instructions, use "click" for buttons (rather than "hit" or "press") and "press" for keys (rather than "hit"). For example, "Click Save" or "Press Return."
-
Quotation marks are not necessary around names of things in the interface that are capitalized or around obvious computer terms (for example, table names, system property names, or file names).
-
Whenever possible, especially for symptoms and the environment, use bullet points rather than complete sentences.
For extra credit:
-
Use present tense ("the function is called") rather than future tense ("the function will be called").
-
Avoid the phrase "the below" - use "the following" instead. For example, instead of "See the below example," say "See the following example."
If a screenshot directly follows the text, you don't have to give any physical direction at all. (Use "as shown in the screenshot" or do not include any introductory text.)
-
Say "use" rather than "utilize." ("Utilize" means to use something in a way in which it is not intended, for example, "utilize a book as a hammer.")
Attachments and Screenshots
Attachments
-
Attachments are searchable so make sure that they are relevant, contain only appropriate information for the audience, and are not overly broad.
-
Make sure that items attached to Public articles contain only information suitable for an external audience, with no customer information or internal information such as internal server names, URLs, or employee logins, and so on.
-
If the attachment is a script or XML file, make sure for Public articles that it is runnable externally and that it does not contain any internal references such as internal server names.
-
Use meaningful names for attachment files rather than generic descriptions such as "pastedimage1.png" or "Screen Shot 2017-12-18 at 3.05.35 PM.png" or "NewScript.xml."
Screenshots
Include a screenshot if you think that a visual will help readers more quickly understand a location in the interface or an illustration of the issue.
-
Illustrations are not searchable so make sure that you are not using them to substitute for text explanations.
-
Do not include numerous callouts that repeat or are substitutes for sequential actions.
-
Size your image so that it does not require too much horizontal scrolling. Make the image as small as possible while still illustrating the necessary area. Consider cropping images to be able to enlarge and emphasize the specific area relevant to the issue.
-
Insert graphic attachments in the text and do not reference them via URL.
-
Make sure screenshots do not contain any customer information or internal information such as employee login names, URLs, and so on.
Guidelines for Writing Steps to Reproduce
-
Make sure your steps to reproduce are clear: the person needing help might not be the one who created the issue or someone who is familiar with the product area.
-
Include the context for actions. Do not assume that the reader knows where all items and choices are located.
-
Provide enough information for the reader to accomplish the step.
-
Do not include too many actions in a single step.
-
Try to put only actions as the step text and put explanatory information on a separate line underneath the step.
-
Use numbered steps rather than bulleted lists or paragraphs for sequential actions.
-
To ensure correct numbering, use the ordered list icon in the toolbar to create an ordered list and list items within the list. The HTML tagging appears as follows:
<ol>
<li>Navigate to … > …</li>
<li>Second action.</li>
</ol> -
To access an HTML view of the Steps to Reproduce and Workaround fields, click in the text and then click the HTML coding ( <> ) icon in the toolbar.
Link Construction
When creating links, construct useful clickable links.
- When providing a sample URL:
- use <instance-name> as replaceable variable text in the URL where an instance name is needed: eg: https://<instance-name>/nav_to.do?uri=...
- or use only the part of the URL without the domain name, eg: /nav_to.do?uri=...
- Be sure not to include internal instance names in articles with the Audience set to Public.
-
Do not style sample URLs as if they were clickable links. Remove any automatic insertion of the <a> tags surrounding the URL. They should appear as regular article text.
-
Do not use the link text "here." For example, instead of saying "For more information about creating a table, click _here_," say "For more information, see the product documentation topic _Create a table_."
-
For links to product documentation, use the documentation topic title as the link text rather than the URL.
-
Set the link to open in a new window/tab so it does not replace the open article in the current window/tab. Within the <a> tags, include target="_blank" as well as the href= URL.
Formatting
- Headings: if you need to separate your content in different sections, use the Heading levels (HTML <h1> to <h6> tags) available in the drop-down labeled "Paragraph". You should only use the levels from 3 downwards because the names of the article template sections are already level 3 (<h3>), for example, Description and Additional information. For consistency, we should only use Heading 3, 4, 5, and 6 if needed. For clarification, this content pre-dates the Table of Contents feature, and is primarily intended to reference templates which are not using a Table of Contents.
-
Apply typographic styling by using the icons in the toolbar:
- Do NOT change the default font by using any of the fonts available in the font type drop-down. Doing this will affect the consistency of the look and feel of the knowledge base. The only exception is the use of the monospace font Andale Mono when needed (code samples, log output, property names, etc.), as described in the typesetting conventions (see KB0623104 in the Additional Information section).
-
Many items in the interface are usually bolded (for example, field names, menu option names, button names, and the like).
-
For commands or small code examples, consider using a monospace font. (Select the text and choose the preferred "Andale Mono" from the Font Family drop-down menu in the toolbar.)
For larger code examples or script snippets, consider using the "Preformatted" paragraph style available in the toolbar, a boxed format with a monospaced font. (Use the <pre> HTML element rather than constructing a table.)
-
Don't use colored text or a larger font for emphasis. Instead, use a bold font, italic text, or a combination of both, always keeping in mind the HI KB Article Typesetting Conventions - KB0623104
-
To access an HTML view of the article fields, click in the text area and then click the HTML coding ( <> ) icon in the toolbar.
