Skip to content

Commit b55c3d6

Browse files
Update contents-of-a-github-docs-article.md (#59349)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent a31ee09 commit b55c3d6

1 file changed

Lines changed: 6 additions & 11 deletions

File tree

content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -53,20 +53,15 @@ Titles can be challenging. Use these general guidelines to help create clear, he
5353

5454
## Intro
5555

56-
The top of every page has an intro that provides context and sets expectations, allowing readers to quickly decide if the page is relevant to them. Intros also are displayed in search results to provide contextual information to help readers choose a result.
56+
Every page and article has an intro which describes what they’re about. The text we use for intros is also displayed within search results, making them important for SEO.
5757

5858
### How to write an intro
5959

60-
* Article intros are one to two sentences long.
61-
* Map topic and category intros are one sentence long.
62-
* API reference intros are one sentence long.
63-
* The intro for an API page should define the feature so that someone knows whether the feature meets their needs without reading the entire article.
64-
* Intros contain a high-level summary of the page’s content, developing the idea presented in a title with more detail.
65-
* Use approachable synonyms of words in the page’s title to help readers understand the article’s purpose differently. Avoid repeating words from the title when possible.
66-
* Intros are relatively evergreen and high-level, so they can scale with future changes to the content on the page without needing to be frequently updated.
67-
* For searchability, include keywords on the page's subject in the intro.
68-
* When a term in the intro has an acronym we’ll use elsewhere in the article, indicate the acronym.
69-
* Intros generally don't contain permissions for any tasks contained within the article.
60+
* Intros should be concise, ideally one sentence long.
61+
* Intros help people know if they’re in the right place for what they need. Let the user know what value is being provided to them, using words they would use and search for.
62+
* Intros are also an invitation to continue reading. A good intro reassures the reader that their time is being well spent.
63+
* If an important term has a related acronym that is generally used in its place, include the acronym in the intro. (Example: Search engine optimization and SEO.)
64+
* Finally, review your intro to ensure it is search engine friendly by including relevant keywords and phrases.
7065

7166
## Permissions statements
7267

0 commit comments

Comments
 (0)