Overview
This is a set of general instructions about how to write a support article for Modern Retail. This guide details what kinds of articles Modern Retail uses, how to format those articles, and the best way to write the content in those articles for client consumption.
General Article Style
Modern Retail support articles should come in two basic shapes:
Knowledge Articles
Knowledge articles typically explain or explore a feature or function. They’re ideal for giving a broad view of the more complicated aspects of web development.
Format
Knowledge articles should begin with a title that reflects what the article is about, then an “Overview” section summarizing the information (if the article is long enough), followed by subsections using Heading 2, Heading 3, and Heading 4 in Zendesk. Knowledge articles should have at least one image somewhere in the article, if not more (where applicable). Care should be taken with titles and subsections to make sure the text doesn’t wrap around on the page (45-50 characters, or 6-7 words is usually the upper limit).
Overview
Most knowledge articles should have an overview section summarizing the scope and information found in the article. This overview shouldn’t be more than one short paragraph, and shouldn’t simply restate information from later in the article. Instead, the overview should clarify the reason for the article-for example, if the reader is looking through multiple articles to find the answer to their problem, the overview should let them quickly determine which is the right article to read. An article does not need an overview if it’s sufficiently short; a good rule of thumb is to skip an overview if it would be more than a third of the total article length.
The overview subsection title should be in Heading 2, and should be followed by another Heading 2 section, not a Heading 3 or 4.
Q&A Articles
Q&A Articles are articles written in response to a common or widely applicable support question. They may use the wording of the original question, or something similar enough to get the point across while increasing clarity. Original names from the support request should be completely replaced.
Format
Q&A Articles should be formatted into two main parts, like so:
- Question (Heading 2)
- Answer (Heading 2)
Both the “Question” and “Answer” sections should use ZenDesk’s Heading 2. The answer section may feature subsections using Heading 3, Heading 4, etc. Unlike Knowledge articles, Q&A articles do not need to have an Overview section.
Universal Standards for Modern Retail Writing
Title
All named articles should have a title that clarifies what the article is about. This title should be clear, but not long enough to cause the text to wrap around on the page. In general, avoid going over 45 characters, or 7 words (best practice is to check after publishing an article.) The title should use relevant keywords in line with good SEO practice. Make sure to double check appropriate spelling and capitalization (for keywords, but also in general). Article titles and subsection titles should never be bold or italicized, and should instead use Headings 2, 3, or 4.
Headings
Articles should use Heading 2, Heading 3, etc. to denote subsections. This breaks the article up to make it easier on the reader, either to read the whole thing, or to find specific pieces of information. While some articles may be too short to make good use of subsections, most should have at least a few. Heading 1 should never be used.
Numbered Lists
Numbered lists make lists of actions easier to read. Numbered Lists should be used when listing a set of ordered actions, like so:
- Go to the webpage
- Go to the settings tab
- Scroll down to “font size”
- Set font size to 12
- Hit “Save”
Lists of directions should almost always be formatted into a numbered list, especially if they’re longer than 2 steps.
Bullet Points
Meanwhile, bullet points should be used for any other lists, specifically those listing objects, links, or pieces of related information, like so:
- Apples
- Oranges
- Papayas
Or
- My friend Shaz is cool
- They have a cat named Oliver
- They work as a florist
Not all lists will require bullet points, but often bulleted lists are a better way of presenting linked pieces of information, especially if they’re longer than one line of text.
Bullet points should exclusively be used for this, rather than for indentation or emphasis.
Bold Text
Bold text should be used sparingly in all articles. Too much bold text clutters the article, and makes it difficult for the reader to know what to pay attention to. Bold text should not be used for words like “all”, “not”, or “never”. Instead, bold text should exclusively be used to refer to the full name of an element from an image or website.
For example, in the above screenshot, “Ecommerce Item” is appropriately bolded, because it refers to the “Ecommerce Item” checkbox in the image.
Additionally, titles in articles should use Heading 2, 3, or 4, and not bold text.
Referring to Features, Images, and Websites
When referring to something in an image or on a website, always use the full visible name rather than shorthand or euphemism. For example in the screenshot above, “Image File” should be referred to as “Image File”, and not “Image”. Double check what you’re referencing to make sure you’re using the same title. If you intend on noting an element from a screenshot or website in specific, using bold text may be appropriate.
Images
Images should be featured in most, if not all, articles, and should be labelled in an SEO appropriate way. Images should be uploaded in their native size, not shrunk. Images typically should not have any special alignment (left, center, or right). Care should be taken to ensure an image is zoomed out enough to give the reader enough information to locate any relevant elements, like drop downs, options, etc. Likewise, images should not be so zoomed out that
Complexity & Audience
When writing a support article or any other text, consider your audience. For support in specific, material should be written for clients who are unfamiliar with web design or basic IT information. Avoid overly technical language and reliance on common knowledge. Instead, focus on describing things so someone brand new to a given feature or task can understand. In general, more description is better than less. A good example of this is avoiding the usage of acronyms; while we as "experts" might recognize "WC" as WooCommerce, a prospective client likely will not.