Overall Purpose:
The purpose of ACME Solutions articles is to create documentation that introduces all of the ACME concepts and explains how to use them in a very clear and straight-forward way. The documentation should also be searchable and as evergreen as possible.
| Point of View | All documentation should be written in a second-person point of view. |
| Formality and Complexity of Language | Documentation should be clear and concise. Use a basic english vocabulary. Tone should be more friendly than formal. |
| Formatting | Use section headings when introducing a new concept (ex: Introduction, Adding a Ticket Type, Sample Use Cases, etc.) Use bullets when appropriate. Use numbered lists when enumerating steps in a process. |
| Images and Screenshots | Should be used to emphasis or compliment a written point. Callouts will be made with a branded color file. Images should be justified to the left side of the document with a shadow effect. |
| Think Search | Think about terms that people might search for when trying to accomplish the task you're documenting and include those terms in your document. Ex: "Add a new ticket type" should be somewhere in your document about ticket types. "Adding a new one," though it makes sense in context, is not helpful to search. |
| Voice | Use the active voice - the subject preforms the action. Remember in second-person writing, the subject is often the "understood you." Ex: Click on "Save & Exit." Assign a price to the ticket type in the price list. Be assertive. Readers get confused by words like "should," "may," and "can." Ex: "Select the dates and times for the event," not "you should then select the dates and times for the event." Be clear. Clarity is the key here so if you need to throw out one of the rules above to clearly communicate the concept, do it. |
| Attention to Detail | When referencing buttons or text objects on the ACME platform, be sure to use the exact spelling as it appears in the system, particularly when capitals and hyphens are used. |
Template
Overview:
Hi there! I am overview text to give the reader a high-level understanding of what the purpose of this article is and what they will learn. You can highlight over this text with your copy to keep the formatting intact.
Section 1:
I am the first section of the article. I might describe what requirements are needed or other dependencies. You can insert bullet or numbered points beneath me and insert images as needed.
(Image Placeholder. Be sure to leave a remark here so the visual editor knows what screen to grab and what it should call out)
Section 2:
This is where you start listing steps needed to resolve an issue or to configure a feature in ACME. Remember that a graphic can be used to add context to your copy but it should not do all of the talking for you.