Documentation
As developers of ecommerce tools and services, we write a lot of technical documentation. It appears in our Knowledge Base and is linked to throughout our themes, apps, and onboarding content.
This section will lay out our guiding principles for documentation, discuss how we structure and style articles, and outline some best practices for keeping documentation relevant and up to date.
Basics
It’s safe to say that someone reading documentation is probably not doing so for pleasure. More likely they’re troubleshooting or at least looking to answer a specific question. With that in mind, we try to make our documentation as simple and focused as possible, providing clear, actionable answers to common queries and problems.
Before we start drafting new documentation, we always ask the following questions:
Why are we writing the article? Defining the “why” before drafting the “how” helps identify puzzle pieces and determine how they fit together.
Who is the article for? Think about the intended reader. Are they a prospective customer, an ecommerce rookie, or a seasoned pro?
Where does it fit within the Knowledge Base? Assessing existing documentation helps identify what’s already been written on a topic and determine whether or not a new article is needed.
What one specific question will this article answer? Complex topics can require long explanations, but shorter and more specific articles are generally preferred. Rather than covering multiple, related topics in a single article, stick to the topic at hand, offering links to further learning.
Structure and styling
When writing documentation, we follow the points outlined in the Voice and tone and Language and grammar sections. We tend to use fewer jokes and idioms in technical articles, and we always address users directly (meaning we use "you" instead of "we" or "one"). It's also important to note that we use American spellings in all our documentation.
Headings/Titles
Write simple, specific article titles. Readers should be able to tell at a glance what question(s) are answered in an article.
Use sentence case, capitalizing only the first letter and names of products and platforms.
How to update your Shopify theme
How to change your Pixelpop plan and payment details
Avoid nouns, verbs, and adjectives ending in -ing.
How to style your Pixelpop popup
Style your Pixelpop popup not Styling your Pixelpop popup
Titles should be simple statements, not questions.
How Pixelpop counts popup views
not How does Pixelpop count popup views?
Subheadings
Subheadings (H2, H3, etc.) help break up ideas and direct readers toward the content they’re looking for. Use H2s to organize content by higher-level topics or goals, and H3s within each section to separate supporting information or tasks. Subheadings should always take sentence case.
Step-based instructions
Ordered or numbered lists are great for step-by-step instructions. Begin step-based articles with a brief outline of an article’s focus, then write instructions as short, sequential steps. Each step should be a single sentence or paragraph, with no more than two related actions per step.
Bold and italicized text
Use bold text to orient readers to specific in-app/theme links, buttons, and menu items.
To preview your published popup, click the Preview button on the popup’s card below the Performance window.”
If you're providing directions for accessing a particular setting or feature, use bold text to identify the steps, separated by a greater-than symbol (">").
To change the font color, go to Customize > Theme settings > Colors.
Unfortunately, italicized text renders weirdly in Help Scout, so try to stay away from it for the time being.
Screenshots and GIFs
Images add context and make content easier to understand. Crop screenshots tightly around the action, or use CloudApp's annotation feature to draw attention to a specific area.
GIFs are great for demonstrating multi-step processes. Use them sparingly, but don't shy away from adding one if it's helpful.
Don't forget to add alt text to all images!
Formatting code
Sometimes it's necessary to include snippets of code to show where a piece of styling lives or how to add a feature to a theme file. Call out code using backticks or the code formatting tool in the text editor.
Anchor links
Anchor links let readers jump to a specific part of an article. If your article is particularly long or text-heavy, consider creating a table of contents and using anchor links for quick navigation. We also use anchor links to link to documentation from within themes and apps (often via help-out boxes) so it's important to set them up properly in Help Scout.
Upkeep
In an industry like ecommerce, the work is never really done. We're constantly iterating and improving our products, and it's essential that our documentation keeps up. Here are a few tactics we've devised to keep things relevant and up to date.
Perform regular audits of documentation to ensure that content (copy and images) matches the most recent theme/app release.
Compare recent entries in release notes and/or changelogs to ensure changes have been noted in documentation.
Attend product meetings or monitor Slack to stay apprised of new products and features.
Regularly check app/theme anchor links (often referred to internally as "help-out links") to ensure they're set up and functioning properly.
Last updated
