Primer
Product UI

Documentation

Primer documentation should express the voices and contributions of different people, but for it to be useful it’s important to be consistent in tone and structure.

Please read and follow these guidelines carefully when writing documentation, so that as many people as possible can benefit from Primer.

Primer documentation principles

Concise but friendly

A large proportion of readers want to find an answer that helps them complete a task, so don't waste their time with unnecessary words. That doesn't mean talking like a robot though: a sprinkling of humor is fine as long as it doesn't make the documentation harder to parse or distract from instructions.

Universally understood

Avoid using phrases or referencing examples that are only familiar internally at GitHub. Assume readers are either members of the public or new to GitHub.

Production quality

Code examples should promote what we'd like to see used in production. People copy and paste code examples as a starting point for building interfaces, and/or reference the guidelines for examples of correct implementation. While examples might be simpler than what we'd use in production, the code should promote best practices and follow our principles and accessibility standards.

Audience

Primer documentation is primarily aimed at GitHub designers and engineers at various levels of experience, but folks in other areas will also benefit from and use the guidelines.

Assumed knowledge

Do:

  • In design docs, assume the reader knows basic design concepts and principles, such as the need for consistency, and terms such as “white space” or “scale”.
  • When referring to GitHub-specific terminology, link to a glossary of terms, or another document where the reader can learn more.
  • When referring to terms and ideas the reader may want to know more about, link to authoritative sources, such as MDN and the W3C.
  • In non-engineering docs, use code examples as necessary to ensure consistency and appropriate usage, but don't assume expertise in any programming language.

Don’t:

  • Don’t assume the reader knows about internal GitHub terminology.

Voice and tone

  • Write as you speak, then tidy it up.
  • Write affirmative sentences wherever possible.
  • Be clear and concise.
  • Use imperative mood, so that instructions are clear.
  • Remove unnecessary words, like adverbs, and keep sentences and paragraphs short.
  • Don’t sound like a robot or too formal.
  • Don’t use sarcasm or irony, they may not translate well.
  • Avoid double negatives.
  • Avoid using expressions like “easy”, “simply”, “quick”, “just”.
  • Avoid idioms, they can be hard to understand and translate.
    • Do: “As a general rule”
    • Don’t: “As a rule of thumb”
  • Don't use the passive voice to avoid using the word “you” (but remove it if unnecessary).
    • Do: “Open Figma”, “Submit an issue if you find a bug”
    • Don’t: “Figma can be opened”, “You can open Figma”, “If a bug is found, submit an issue”
  • Avoid the possessive "our", and avoid addressing Primer as "our design system”.
    • Do: “In the Figma library…”
    • Don’t: “In our Figma library…”
  • Use "we" consistently to refer to the Design Systems / Infrastructure team, not to GitHub as a whole.

Grammar and usage

Follow the GitHub content guidelines (this link is only accessible to GitHub staff), in particular:

  • Follow US spelling.
    • Do: “Color palette”
    • Don’t: “Colour palette”
  • Use sentence case for titles.
    • Do: “Utility classes”
    • Don’t: “Utility Classes”
  • Capitalize only proper nouns and product names (this link is only accessible to GitHub staff).
    • Do: “Open a pull request"
    • Don't: "Open a Pull Request"
  • Avoid positional language.
    • Do: “The list that follows”
    • Don’t: “The list below”
  • Use contractions.
    • Do: “Don’t use this class”, “We’re happy to see you!”
    • Don’t: “Do not use this class”, “We are happy to see you.”
  • Exclamation points are OK, in moderation.

You may also refer to the content style guide for GitHub Docs, in specific:

Images and other examples

Most component usage examples should be visualized using the live editable code examples. For example, we show the Button style variants by rendering each variant.

However, there are some cases where a static image is more appropriate. For example, when showing "Do" and "Don't" examples, we wouldn't want to show Primer consumers how to "hack" a component to implement the "Don't" example.

Create new assets in the Interface guidelines Figma (available to GitHub staff only) to create images that are consistent across Primer documentation.

When creating images with example UI for docs make sure that:

  • All documentation examples should be of real github.com examples
  • Examples only include the most important part of the UI, and don't try to show the entire UI
  • Use meaningful copy (for example, use "New issue" instead of "Button" as the text inside a button)

Rendering static images in docs

Use the FigmaImage component (available to GitHub staff only). This component uses the figma-images utility to export assets directly from Figma.

This workflow that the images in the docs are always up to date with the latest changes in the Figma file, and we'll always have a link back to the original asset.

Adding a new image using FigmaImage

  1. Create your asset for the "light" and "dark" color modes in two frames on the appropriate page of the Interface guidelines Figma (available to GitHub staff only).
  2. Render the <FigmaImage> component in your .mdx file.
  3. Paste the link to the "light" mode frame in the src prop, and the link to the "dark" mode frame in the darkModeSrc prop.
  4. Run npm run build:figma-images before starting the dev server (npm run dev)
  5. Ensure you have a .env.local file with the FIGMA_TOKEN environment variable set to a valid Figma API token. For example: FIGMA_API_TOKEN=figd_xxxxxxxxxxxxxxxxxxxxxxx.
    You can learn how to generate a new token here.
  6. Optional: Add alt text if the image is not purely presentational.
  7. Optional: Use the height, width, or fillParentWidth props to adjust the size of the image to fit in your layout.
  8. Optional: Use the caption prop to render a caption below the image.
Example: 
<FigmaImage
  src="{light mode frame url}"
  darkModeSrc="{dark mode frame url}"
  alt="A SegmentedControl component with three segments: 'All', 'Open', and 'Closed'."
  caption="SegmentedControl being used to filter issues by state."
/>

References

  • If mentioning or referring to other styles and documentation, always link to the source.
  • Reference an existing guide by linking to it, rather than duplicating the content. However, if this makes the documentation harder to follow, consider providing that reference in the document itself (for example: spacing scale, abbreviations).

Publishing checklist

  • Spellcheck text with an automated tool
  • Spellcheck UI text in image examples
  • Ask someone else to proofread the document including images - they may catch something you missed
  • Test all the links
    • Indicate links that only work for GitHub staff (for example, "for GitHub staff only", or "only accessible to GitHub staff")
  • Verify there isn’t any private or sensitive information
  • Verify that all images include an alt text

Documenting components

Focus on the essential details that clearly communicate the component’s purpose and how it should be used within the UI.

Documentation preferences

  • Use PascalCase when referring to component names.

    • Do: AvatarStack displays two or more Avatars in an inline stack.
    • Don't: Avatar stack displays two or more avatars in an inline stack.

  • When writing the component description, introduce the component directly, without "a" or "an":

    • Do: ActionMenu is a component based on ActionList for creating a menu of actions that expands through a trigger button.
    • Don't: An ActionMenu is a component based on ActionList for creating a menu of actions that expands through a trigger button.

Component descriptions

The description appears directly under the title of the component.

This description should be concise and shouldn't include usage information, which is covered below this section.

When writing a description, consider the question "What is this component, and how would you describe it to someone who has never used it before?"

Component documentation structure

Overview

The "Overview" tab is a high-level summary of the component, and should include:

  • Info about the component's implementations (React, Rails, and Figma)
  • React examples that demonstrate common use classes
  • React examples that demonstrate component options such as style, size, and layout variants
  • Component API documentation
  • If applicable, a set of related links to other documentation, such UI pattern guidelines, accessibility documentation, and related components.

Guidelines

The "Guidelines" tab contains the design guidelines for using the component, and may include:

  • Best practices for using the component, including when to use it and when not to use it
  • Do/Don't examples
  • Common pitfalls to avoid
  • Anatomy diagram and supporting text that describes the elements that make up the component. See ActionList as an example.
  • Content and copywriting guidance
  • Layout and responsive design considerations
  • Different applications of the component in context
  • If there are specific behaviors or interactions that the consumer of this documentation should be aware of, it's important to document here. Is it clickable, or static, and does it have any specific interactions based on state? Are there multiple types of behavior, and when does each get applied? See Autocomplete as an example.

Accessibility

The "Accessibility" tab contains information about the component's accessibility features and guidelines for how to use the component accessibly. This may include:

  • Any component-specific accessibility considerations should be documented. This could include keyboard navigation, touch targets, and any specific usage guidelines with regards to assistive technology. See SegmentedControl.
  • If there are any accessibility issues that need to be addressed, but are not yet resolved, they should be documented here as well.

Minimum-viable component documentation

One of the strategies to help Primer documentation become self-serve is to accurately represent the breadth of patterns and components we have available through our documentation.

Executing on this plan requires us to be practical and concise in terms of the depth of the documentation. In order to ensure we can reach 100% coverage, we may use a "minimum-viable documentation" approach.

Minimum-viable documentation should be:

  • Accurate
  • Informative but concise
  • Visible

Minimum-viable component documentation structure

Minimum-viable description
  • brief text describing what the component is
  • link to available implementations
  • image, if applicable
Minimum-viable usage guidance
  • proper usage guides
  • visual examples, such as an image or gif demonstrating what the component is

Add more documentation if it's readily available

If more information (than required above) is easily accessible and doesn't require a huge time investment to include, it should be added to to the minimum-viable component documentation. Some examples of this include listing out related components, cross-linking to Accessibility guidelines, and more.

Tips and tricks

Recommendations for tackling this work quickly and efficiently

  • Work in pairs or with a small group. Dedicate 1-2 components per person, with each person in the group responsible for reviewing the others' PRs.
  • Timebox each component to x hour(s) for writing, x hour(s) for reviewing, and x hour(s) for writing revisions.
  • If you feel blocked by a lack of information about the component to write useful documentation, contact other Primer contributors to get the context you need.

Review process

All pull requests for new and updated guidelines should be reviewed and approved by a member of the Design Infrastructure team.

Resources