Skip to content

Latest commit

 

History

History
199 lines (106 loc) · 13.5 KB

tech-docs-writing-guide.md

File metadata and controls

199 lines (106 loc) · 13.5 KB
Raw

Writing guide for Platform Services technical documentation

Use this guide to reference the approach taken to rewrite the Platform Services technical documentation. While this document is a good place to start, it's still alive and breathing and can be modified and improved upon as needed. Don't be shy. Documentation should evolve and improve!

Also, reference the style and terminology guide that's still in development for more specific rules. Keep in mind that the style guide tracks rules for granular usage of terms or formatting and is built around decisions made during the writing process by writers and stakeholders.

When you're ready to start a new document, copy the new Markdown document template.

On this page

Formatting

Use the following guidelines for basic formatting.

  • Define abbreviations at first use.

    The only exception is if you're confident that the audience understands the abbreviation or it's so common that most people would know. For example, PDF, JPEG.

  • Spell out numbers one to ten, use digits for everything after.

    For more guidance and exceptions, see Writing numbers and dates in web content.

  • Rules for lists are clearly laid out in the Web Style Guide.

  • When writing code or commands, generally set them on their own line, like so:

    code example that seriously rocks

Tone and voice

The Grammar, spelling and tone section of the Web Style Guide thoroughly covers tone and voice, but here are the most important points to keep in mind:

  • Avoid the passive voice and use verb-forward language. The best way to eliminate passive voice is to consider the person or thing performing the verb in the sentence you're writing. Who does what? Even if it's a thing and not a person. For example, a program notifies a person.

  • Use contractions.

  • Use simple words and phrases. Replace more complex words and phrases with a simpler alternative, where possible.

  • Write in the present tense.

  • Omit needless verbs, adverbs, and double verbs.

  • Use less jargon. Strike a balance between formal and approachable.

  • Don't use Latin abbreviations (e.g., i.e., etc.). They're not always familiar to non-native English speakers, they don't always get read correctly by screen readers, and people don't speak Latin. Write around them or use the full term.

Audience and perspective

The audience for the technical documentation generally has a high-level of devops knowledge and there are also other avenues for assistance (for example, Rocket.Chat).

Duplicate content

Don't duplicate content across pages. Remember the principle of one topic = one page. Rather than duplicating content, link to content that's needed. There's a couple solid reasons for this:

  • Maintenance: If documentation, information, or processes change, it only needs to be updated in one place. Do your future self a favour.

  • Findability: Having only one topic per page helps users find what the specific topic they need. Users know what's on the page and what they'll get out of reading the page.

For example, from our own tech docs library: BC Government organizations in GitHub. The first draft of this page originally contained three topics:

After getting feedback, these pages needed to be split. Each page now seems pretty clear what they're about and the user doesn't have to wade through the original page to find content on requests or removals.

Essentially, try to put yourself in the shoes of the user and assume they'll want to go directly to the content they need, rather than stumble upon it.

The resources below have more information. They are concerned largely with forms, but similar principles apply to topics:

Linking strategy

The Nielsen Norman Group has extensive and thorough guidance on writing excellent hyperlinks.

Make sure that the link to an external page is descriptive. The user should know (or have a good idea) where the link is going to take them before they click it.

When linking from one Markdown page in the ./src/docs/ folder to another, write the link in the form /<slug of the target page>/. While these links won't work when viewing the page on GitHub, they will work on the Gatsby site.

When linking from Markdown pages in ./src/docs/ to the Cloud WordPress site, use the token %WORDPRESS_BASE_URL% in place of the site address and before the path of the document being linked to, in the form %WORDPRESS_BASE_URL%/path-to-page/. This is to allow for different WordPress URLs to be injected depending on the environment.

FAQs

Don't write FAQs or format sections as a question and answer. Just tell the reader what they need to know.

Page structure and elements

Titles

Use a descriptive and specific title. What does the reader do with the page? What specific information do they gain?

Good titles help with findability and usability.

Use sentence case for titles and headings.

Images

Use images sparingly. If you need to use images, make sure they are supplementary to the writing. Don't rely on them to explain a process.

Consider the following before using an image:

  • Does the image should show something that can't be explained using words?

  • Does the image meet accessibility standards?

  • Will the image require updates in the future? (Remember, help future you)

  • Does the image contain elements that need to be clicked on or interacted with but can't be? For example, hyperlinks.

One final note on images. Writing them in markdown doesn't give a lot of options for display or to implement very specific standards, so image standards may have to be ironed out on the developer end of things.

Also, when placing images in the documents, make sure they have a relative link format. For example, ../../images/image-name.png. This ensures the images appear in the GitHub file and on the tech docs site.

On this page

Use the On this page section as a simple table of contents. See this section on Anchor links.

There is no need to manually add anchor links (like <a name="example"></a>) in order to create the table of contents. Both GitHub and Gatsby automatically generate IDs for all levels of headings using the same rules. When creating the ID, headings are set to lower-case, whitespace is replaced with dashes, and special characters are removed.

Not sure what the ID for your new heading will be? Add the heading to the document and view it on GitHub. Mouse-over the heading and click the link icon to the left of the heading to move the browser to that anchor. Grab the ID from the URL bar.

People

Avoid using people's names in documentation. There are many good reasons for this:

  • They might be away
  • They may have left the position or changed positions
  • Organizational contact methods or means may have changed

You get the idea. Essentially, when you avoid using their name, it means you avoid questions and also don't have to go back and update it later. Use their position or reference more general means of contact. For example, a Rocket.Chat channel or a team email.

Accessibility

Use the BC Government's guidelines and tools to ensure your work is accessible and inclusive.

Writing step-by-step instructions

Occasionally, you'll have to write procedures. Find some of the most useful tips below but also check out Microsoft's best practices for instructions. It's a great crash course.

  • Use numbered and bullet lists but not multi-level lists. Don't write single-item lists.

  • Front load your content. What is the most important part of a given sentence? Give the reader what they need the most as soon as possible.

  • Tell people what they should do, not what they shouldn't do.

  • Here is especially important to write in the present tense.

  • Use specific verbs.

  • When you can, familiarize yourself with tools and programs so you can reference the UI accurately. However, tell the reader what they need to do, rather than getting too specific on the UI. Remember that the audience is already quite technical.

Metadata

We use YAML frontmatter in our Markdown files to add metadata to our documents. These fields are necessary to generate pages properly. Track the metadata in the fields of each page based on these descriptions:

  • title: The title of the page. The best title you can create. Used to generate the <title> tag.

  • slug: Used to generate the page path in the URL. Please use lowercase and separate words with -. Ex: Using slug: landing-page will cause the page to appear on the Gatsby site at /landing-page/.

  • description: A brief, precise description of what a reader will find on the page. Used to generate the <meta name="description"> tag.

  • keywords: These tags are important (see more below) to describe what the page is about. What kind of terms bring a reader here? What will they find? Used to generate the <meta property="keywords"> tag.

  • page_purpose: A more in-depth description.

  • audience: Typically, a developer or a technical lead.

  • author: Whoever wrote the original draft (or drafted the rewrite).

  • content_owner: The SME of the page. They are responsible for the factual accuracy of the content.

  • sort_order: Used to determine the sort order of the page within a navigation menu category.

Keywords, tags, and taxonomy

It's important to track relevant keywords for each page and to refine them as the content becomes clearer. Eventually, the team uses a taxonomy to help pages get found when users search for them. But there are distinct differences, as shown in the quotes from this blog below:

  • "Tags themselves are not taxonomies. You can use your taxonomic terms as tags, but the tags themselves are not taxonomy. Taxonomy is not just a list of words, it’s a controlled vocabulary."

  • "Metadata is information about information. Metadata describes the content and taxonomy organizes the content. Taxonomical terms should be stored as metadata, but metadata itself isn’t taxonomy."

Resources