Skip to content

best-practices-for-github-docs.md

Latest commit

 

History

History
113 lines (82 loc) · 5.22 KB

best-practices-for-github-docs.md

File metadata and controls

113 lines (82 loc) · 5.22 KB
title Best practices for GitHub Docs
shortTitle Best practices for GitHub Docs
intro Follow these best practices to create documentation that is user-friendly, clear, and easy to understand.
versions
fpt ghec ghes
*
*
*

About {% data variables.product.prodname_dotcom %} documentation

At {% data variables.product.prodname_dotcom %}, we aim to create documentation that is accurate, valuable, inclusive, accessible, and easy to use.

Before contributing to {% data variables.product.prodname_docs %}, review {% data variables.product.prodname_dotcom %}'s documentation philosophy, fundamentals, and content design principles:

Best practices for writing {% data variables.product.prodname_dotcom %} documentation

When creating or updating an article, follow these guidelines:

Align content to user needs

Before writing, identify your audience, their goals, and the main tasks or concepts the article will cover.

Define the audience

  • Who is the intended reader?
  • What are they trying to accomplish?

Define the core purpose

  • What should readers be able to do or understand after reading this article?
  • Focus on one or two primary tasks or concepts.
  • Move secondary information lower in the article, to another article, or remove it if unnecessary.

Determine the content type

Choose the content type based on your audience and purpose. {% data variables.product.prodname_docs %} supports:

For example:

  • Use conceptual content to explain what a feature does and why it matters.
  • Use procedural content to guide readers through completing a specific task.

Structure content for readability

When adding content to an existing article, follow its structure whenever possible.

  • Provide initial context. Define the topic and explain why it matters.
  • Organize content logically. Present information in order of importance and in the sequence users need it.
  • Avoid long sentences and paragraphs.
    • Introduce concepts one at a time.
    • Use one idea per paragraph.
    • Keep sentences focused and concise.
  • Highlight key information.
    • Begin with the most important takeaway.
    • When explaining concepts, start with the conclusion, then add supporting details (the “inverted pyramid” approach).
    • Present basic information first, then introduce complexity.
  • Use clear, meaningful subheadings. Ensure each section title accurately reflects its content.
  • Add in-page links for longer articles. This helps readers navigate directly to relevant sections.

Write for readability

Help busy readers quickly understand the content.

  • Use plain language. Prefer clear, everyday words. Avoid unnecessary jargon.
  • Use active voice.
  • Be concise.
    • Write short, direct sentences.
    • Avoid combining multiple ideas in one sentence.
    • Remove unnecessary detail.

For related guidance, see "Voice and tone" in AUTOTITLE and AUTOTITLE.

Format for scannability

Most readers scan or skim documentation rather than reading every word.

When scanning, readers focus on headings, alerts, lists, tables, code blocks, visuals, and the first few words of sections.

Once your article has a clear purpose and structure, use these formatting techniques:

  • Use text highlighting (bold text and hyperlinks) to emphasize key points. Use it sparingly—avoid highlighting more than 10% of the article.
  • Use formatting elements to break up text and create visual structure, such as:
    • Bulleted lists
    • Numbered lists
    • Alerts
    • Tables
    • Visuals
    • Code blocks with annotations

Further reading