If you have access to add articles to the FBRI Help Center (this site), some best practices are listed below. If you have an article suggestion, please Start a Conversation and let us know!
If you find something that needs to be corrected in an existing article, make sure you are logged in and use the comments section on the article page.
ARTICLE DOCUMENTATION BEST PRACTICES:
- Keep it simple. Flowery, extraneous comments and detailed descriptions are only nessisary if they are required to get the point of the article across.
- Use consistent language. Use consistent terms and references. For example, if you are referring to the Enter Key, always use "Enter Key" and not "Return Key".
- Create consistent titles. Titles should be descriptive but not overly so and should follow proper capitalization rules for titles. Title Capitalization Rules. Use statements vs. questions. For example: "Filing an Expense Report" vs. "How do I file an expense report?" or "Viewing Previously Recorded Presentations" vs. "How do I View a Previously Recorded Presentation?"
- Use key words. To help people find your article more easily when they search, use the "Search Keywords" box to the right. For example, for this article I used "article, writing, knowledge base".
- Allow comments. When (and only when) users are signed into the Help Center, they can leave comments. This is important for us to receive feedback and improve their experience. To allow this, leave the default setting of "Allow comments" selected to the right.
- Start a conversation. If you are asking the reader to start a conversation (i.e. submit a request), include the link in your text. To do this, type "Start a Conversation", select the text, then choose the chain link button from the editor tool bar (third from the left in the bottom row).
In the window that opens, type the URL: https://vtcri.kayako.com/conversation/new
into the URL box and click Insert. (TIP: You can right click the "Start a Conversation" link at the top of this page and choose Copy Link or Copy Url and then paste the it into the URL box.)
There is an example of this in step 1 in the section below.
A good example for showing how to document technical steps is below. Note the use of bold for what to click and the use of ">", etc.:
----- BEGIN EXAMPLE -----
To upgrade client software with AutoUpgrade:
In the console, click Admin > Install Packages. If you do not have access to the console, Start a Conversation to place a request and we will provide the access needed.
Under Tasks, click Upgrade Clients with Package.
In the Upgrade Clients Wizard panel, click Next, select the appropriate client installation package, and then click Next.
Select the group or groups that contain the client computers that you want to upgrade, and then click Next.
Select from where the client should download the package from the following options:
To download from the Symantec Endpoint Protection Manager server, click Download from the management server.
To download from a web server that is local to the computers that need to update, click Download from the following URL (http or https). Enter the URL of the client installation package into the provided field.
Click Upgrade Settings to specify upgrade options.
On the General tab, under Client Settings, choose from the following options, depending on the client operating system:
For Windows, use the drop-down menus to select options for Maintain existing client features when updating and Install Settings.
Note: If you deselect Maintain existing client features when updating, you can optionally add or remove features when upgrading.
For Mac, use the drop-down menu to select options for Install Settings.
For either Windows or Mac, Content Selection lets you include content in the installation package. If you include content, the package is larger, but the client has up-to-date content immediately after installation. If you do not include content, the package is smaller, but the client must get content updates after installation.
----- END EXAMPLE -----