Documentation Style Guide

Documentation is a key part of launching a theme on WordPress.com. Ensuring that all necessary information is present and formatted consistently reduces user confusion and frustration, keeping refunds to a minimum (both on showcase and support pages). Once you get in to the habit, generating solid documentation will become second nature in an efficient theme launch.

General

• Include screenshots! Users find screenshots very helpful, particularly annotated screenshots — circle the relevant buttons, add arrows pointing out mentioned links, or highlight key sections.
• All admin-side screenshots need to be of WordPress.com, not a .org install.
• Screenshots should be JPGs, except in the rare case where a PNG would result in a smaller file size.
• Animated GIFs and screencasts are also popular with users. They’re great for demonstrating a series of clicks needed to set up a feature.
• The theme name is always italicized.
• Menu items are italicized, with a proper right arrow: Appearance → Menus.
• Admin links or buttons are bolded: “click Update to save changes.” Make sure to use the button’s exact text.
• Feature names are title-cased: MegaTheme supports Post Formats and Featured Images.
• Feature names are linked to their en.support.wordpress.com page.
• Use Title Case for section titles.
• On WordPress.com, we refer to the core Theme Customizer as simply “the Customizer” (capital “C”).
• Use “homepage”– not “home page”.
• Section titles are <h2>s.
• Subsection titles are <h3>s.
• Don’t add any inline styles to modify sizes or other aspects of headings or other elements.
• Spell out numbers nine and under. Use numerals for 10 and up.
• Proper English spelling and grammar are required. If English is not your first language, consider hiring a translator or native speaker to assist with the documentation (automated translation services such as Google Translate will not be accepted).
• Use US (American) spelling and punctuation conventions, so for example, use  “color” – not “colour.”
• Use a serial (Oxford) comma – that’s the comma before “and” in a list of several items. For example: “This theme is elegant, simple, and easy to use.”
• Refer to the dashboard, not the admin area.

Showcase Page

• A screenshot of the theme, linked to the theme’s demo site, is the first item on the page. Images combining different mobile views are also fine.
• Use the Showcase page to tell users why it’s their perfect theme. Don’t just list every feature; convince the user that your theme will improve their home on the Internet.
• The bottom of each Showcase page should include the Quick Specs section, providing measurements for key elements such as columns and featured images. Use the following HTML as a base:

  <div class="notes">
  Quick Specs (<em>all measurements in pixels</em>):
  <ol>
      <li>The main column width is <code>676</code>.</li>
      <li>The sidebar width is <code>286</code>.</li>
      <li>The footer widget area widths are <code>312</code>.</li>
      <li>Featured Images are <code>676</code> wide by unlimited height on Sticky posts, and <code>1280</code> by <code>416</code> as header images on single posts and pages.</li>
  </ol>
  </div>

• Set a Featured Image for the Showcase page which is an accurate screenshot of the theme at 1024×768.
• Examples of effective Showcase pages are Ubud, Nurture, and Twenty Fourteen.

Support Page

• Content should be broken up into sections by feature (ie. Featured Images, Widgets, Theme Options).
• Each supported feature should include an accurate, step-by-step procedure (users love step-by-step procedures). Keep in mind that not all WordPress.com users are tech-savvy. Duplicating procedures from other theme support pages is fine, as long as they are accurate.
• Consider dedicating a section to making a new blog look like the demo site (certainly if more than just a couple of steps are required). This is a very common pain point with users that have just bought premium themes based on a full-featured demo site.
• Each feature should link to its respective en.support.wordpress.com page. If you mention the same feature in multiple sections, linking it the respective support page at least once per section would be helpful, since users may skip sections when reading through the documents.
• Don’t number your section headings.
• Great examples of support pages are Ubud, Little Story, and The Parisian.