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.
On this page
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.
Aspirational guidelines
Guidelines can be aspirational, as long as what is documented is possible to implement with Primer. Guidelines should document and promote what we want folks to do with Primer, and not cover all possible variations.
Design guidelines should not document patterns that are not possible to create with the current system. If you're writing guidelines for a feature that is upcoming, but not yet ready in implementation, you can have the content ready in a pull request, to be published when the implementation ships.
Use this Figma template (accessible 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)
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
Review process
All pull requests for new and updated guidelines should be reviewed and approved by a member of the Design Infrastructure team.