You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md
+6-11Lines changed: 6 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,20 +53,15 @@ Titles can be challenging. Use these general guidelines to help create clear, he
53
53
54
54
## Intro
55
55
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.
57
57
58
58
### How to write an intro
59
59
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.
0 commit comments