Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://docs.github.com/en/contributing/writing-for-github-docs/best-practices-for-github-docs below:

Best practices for GitHub Docs

Follow these best practices to create documentation that's user-friendly and easy to understand.

At GitHub, we strive to create documentation that is accurate, valuable, inclusive, accessible, and easy to use.

Before contributing to GitHub Docs, please take a moment to familiarize yourself with GitHub's documentation philosophy, fundamentals, and content design principles:

• About GitHub's documentation philosophy
• About GitHub's documentation fundamentals
• Content design principles

Whether you're creating a new article or updating an existing one, you should follow these guidelines when writing for GitHub Docs:

• Align content to user needs
• Structure content for readability
• Write for readability
• Format for scannability

Before you begin, it’s important to understand who you’re writing for, what their goals are, the core tasks or concepts that the article will address, and what type of content to write.

• Who will read this content?
• What are they trying to do?

• What should someone be able to do or understand after reading this article? Choose one or two tasks or concepts that the content will discuss.
• If there are additional tasks, concepts, or information that are not essential, consider if they can be placed lower in the article, moved to another article, or omitted completely.

Determine which type of content you will write, based on the intended audience and the core purpose of the content. GitHub Docs use the following content types:

• Conceptual content
• Referential content
• Procedural content
• Troubleshooting content
• Quickstart
• Tutorial

For example, use the conceptual content type to help readers understand the basics of a feature or topic and how it can help them accomplish their goals. Use the procedural content type to help people complete a specific task from start to finish.

Use the following best practices to structure the content. When adding content to an existing article, follow the existing structure whenever possible.

• Provide initial context. Define the topic and state its relevance to the reader.
• Structure the content in a logical order by importance and relevance. Place information in order of priority, and in the order users will need it.
• Avoid long sentences and paragraphs.
  • Introduce concepts one by one.
  • Use one idea per paragraph.
  • Use one idea per sentence.
• Emphasize the most important information.
  • Begin each sentence or paragraph with the most important words and takeaways.
  • When explaining a concept, start with the conclusion, then explain it in more detail. (This is sometimes called an "inverted pyramid.")
  • When explaining a complex topic, present readers with the basic information first, and disclose the details later in the article.
• Use meaningful subheadings. Organize related paragraphs into sections. Give each section a subheading that is unique and that accurately describes the content.
• Consider using in-page links for longer content. This allows readers to jump to areas of interest and skip content that is irrelevant to them.

Make it easy for busy users to read and understand the text.

• Use plain language. Use common, everyday words, and avoid jargon when possible. Terms that are well known to developers are fine, but don't assume that the reader knows the details of how GitHub works.
• Use active voice.
• Be concise.
  • Write sentences that are simple and brief.
  • Avoid complex sentences that contain multiple concepts.
  • Pare down unnecessary details.

For related information, see "Voice and tone" in Style guide and Writing content to be translated.

Most readers don't consume articles in their entirety. Instead they either scan the page to locate specific information, or skim the page to get a general idea of the concepts.

When scanning or skimming content, readers skip over large chunks of text. They look for elements that are related to their task or that stand out on the page, such as headings, alerts, lists, tables, code blocks, visuals, and the first few words in each section.

Once the article has a clearly defined purpose and structure, you can apply the following formatting techniques to optimize the content for scanning and skimming. These techniques can also help to make content more understandable for all readers.

• Use text highlighting such as boldface and hyperlinks to call attention to the most important points. Use text highlighting sparingly. Do not highlight more than 10% of the total text in an article.
• Use formatting elements to separate the content and create space on the page. For example:
  • Bulleted lists (with optional run-in subheads)
  • Numbered lists
  • Alerts
  • Tables
  • Visuals
  • Code blocks and code annotations

• Style guide
• About the content model
• Contents of a GitHub Docs article
• Readability Guidelines, Content Design London
• Rewriting Digital Content for Brevity, Nielsen Norman Group

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4