Add style guide to Contribute to the docs #4060

theletterf · 2025-11-24T15:16:15Z

Summary

Brings the docs style guide and the good docs issues howto to the contribution section.

Fixes https://github.com/elastic/docs-content-internal/issues/339

Generative AI disclosure

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

Tool(s) and model(s) used: Cursor with Claude Sonnet 4.5

github-actions · 2025-11-24T15:18:10Z

Vale Linting Results

Summary: 41 warnings, 137 suggestions found

⚠️ Warnings (41)

File	Line	Rule	Message
contribute-docs/style-guide/accessibility.md	127	Elastic.Accessibility	Don't use language (such as 'vision-impaired') that defines people by their disability.
contribute-docs/style-guide/accessibility.md	162	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
contribute-docs/style-guide/accessibility.md	215	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'using' instead of 'via'.
contribute-docs/style-guide/formatting.md	173	Elastic.EndPuntuaction	Don't end headings with punctuation
contribute-docs/style-guide/grammar-spelling.md	40	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
contribute-docs/style-guide/grammar-spelling.md	49	Elastic.Gender	Don't use 'he/she'.
contribute-docs/style-guide/grammar-spelling.md	303	Elastic.BritishSpellings	Use American English spelling 'visualization' instead of British English 'Visualisation'.
contribute-docs/style-guide/grammar-spelling.md	317	Elastic.BritishSpellings	Use American English spelling 'organize' instead of British English 'organise'.
contribute-docs/style-guide/grammar-spelling.md	318	Elastic.BritishSpellings	Use American English spelling 'authorize' instead of British English 'authorise'.
contribute-docs/style-guide/grammar-spelling.md	319	Elastic.BritishSpellings	Use American English spelling 'analyze' instead of British English 'analyse'.
contribute-docs/style-guide/grammar-spelling.md	327	Elastic.BritishSpellings	Use American English spelling 'flavor' instead of British English 'flavour'.
contribute-docs/style-guide/grammar-spelling.md	328	Elastic.BritishSpellings	Use American English spelling 'color' instead of British English 'colour'.
contribute-docs/style-guide/grammar-spelling.md	329	Elastic.BritishSpellings	Use American English spelling 'behavior' instead of British English 'behaviour'.
contribute-docs/style-guide/grammar-spelling.md	337	Elastic.BritishSpellings	Use American English spelling 'license' instead of British English 'licence'.
contribute-docs/style-guide/grammar-spelling.md	338	Elastic.BritishSpellings	Use American English spelling 'defense' instead of British English 'defence'.
contribute-docs/style-guide/grammar-spelling.md	339	Elastic.BritishSpellings	Use American English spelling 'pretense' instead of British English 'pretence'.
contribute-docs/style-guide/grammar-spelling.md	347	Elastic.BritishSpellings	Use American English spelling 'dialog' instead of British English 'dialogue'.
contribute-docs/style-guide/grammar-spelling.md	348	Elastic.BritishSpellings	Use American English spelling 'catalog' instead of British English 'catalogue'.
contribute-docs/style-guide/grammar-spelling.md	349	Elastic.BritishSpellings	Use American English spelling 'epilog' instead of British English 'epilogue'.
contribute-docs/style-guide/seo.md	5	Elastic.DontUse	Don't use 'just'.
contribute-docs/style-guide/seo.md	44	Elastic.DontUse	Don't use 'very'.
contribute-docs/style-guide/seo.md	266	Elastic.MeaningfulCTAs	Use meaningful link text. Use 'visit, go to, refer to' instead of 'click here'.
contribute-docs/style-guide/ui-writing.md	30	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
contribute-docs/style-guide/ui-writing.md	33	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
contribute-docs/style-guide/ui-writing.md	70	Elastic.DontUse	Don't use 'just'.
contribute-docs/style-guide/ui-writing.md	70	Elastic.DontUse	Don't use 'just'.
contribute-docs/style-guide/ui-writing.md	98	Elastic.DontUse	Don't use 'very'.
contribute-docs/style-guide/ui-writing.md	192	Elastic.DontUse	Don't use 'and/or'.
contribute-docs/style-guide/ui-writing.md	193	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
contribute-docs/style-guide/ui-writing.md	193	Elastic.QuotesPunctuation	Put punctuation outside the quotation marks.
contribute-docs/style-guide/ui-writing.md	195	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'versus' instead of 'vs'.
contribute-docs/style-guide/voice-tone.md	31	Elastic.DontUse	Don't use 'just'.
contribute-docs/style-guide/voice-tone.md	48	Elastic.DontUse	Don't use 'very'.
contribute-docs/style-guide/voice-tone.md	49	Elastic.BritishSpellings	Use American English spelling 'among' instead of British English 'amongst'.
contribute-docs/style-guide/voice-tone.md	303	Elastic.DontUse	Don't use 'very'.
contribute-docs/style-guide/voice-tone.md	305	Elastic.DontUse	Don't use 'Please'.
contribute-docs/style-guide/voice-tone.md	305	Elastic.DontUse	Don't use 'please'.
contribute-docs/style-guide/voice-tone.md	305	Elastic.DontUse	Don't use 'please'.
contribute-docs/style-guide/voice-tone.md	305	Elastic.EndPuntuaction	Don't end headings with punctuation
contribute-docs/style-guide/voice-tone.md	307	Elastic.DontUse	Don't use 'please'.
contribute-docs/style-guide/voice-tone.md	311	Elastic.DontUse	Don't use 'Please'.

💡 Suggestions (137)

File	Line	Rule	Message
contribute-docs/how-to/good-issues.md	17	Elastic.Wordiness	Consider using 'because' instead of 'since'.
contribute-docs/how-to/good-issues.md	73	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	8	Elastic.Acronyms	'WCAG' has no definition.
contribute-docs/style-guide/accessibility.md	35	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	91	Elastic.DeviceAgnosticism	Use device-agnostic language when possible. Use 'select' instead of 'tap'.
contribute-docs/style-guide/accessibility.md	94	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	127	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	150	Elastic.WordChoice	Consider using 'efficient' instead of 'simple', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	162	Elastic.Negations	Consider rephrasing to avoid negative constructions like 'cannot access the content without'. Try stating what something IS rather than what it is NOT.
contribute-docs/style-guide/accessibility.md	170	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	172	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	182	Elastic.Wordiness	Consider using 'because' instead of 'since'.
contribute-docs/style-guide/accessibility.md	190	Elastic.WordChoice	Consider using 'can, might' instead of 'May', unless the term is in the UI.
contribute-docs/style-guide/accessibility.md	191	Elastic.Acronyms	'RFC' has no definition.
contribute-docs/style-guide/accessibility.md	226	Elastic.Wordiness	Consider using 'impossible' instead of 'not possible'.
contribute-docs/style-guide/accessibility.md	228	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/accessibility.md	229	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/formatting.md	12	Elastic.Acronyms	'MDX' has no definition.
contribute-docs/style-guide/formatting.md	65	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
contribute-docs/style-guide/formatting.md	96	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/formatting.md	122	Elastic.FutureTense	'you'll use' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/formatting.md	220	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/formatting.md	220	Elastic.WordChoice	Consider using 'efficiently' instead of 'easily', unless the term is in the UI.
contribute-docs/style-guide/formatting.md	288	Elastic.FutureTense	'will help' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/formatting.md	288	Elastic.WordChoice	Consider using 'efficiently' instead of 'easily', unless the term is in the UI.
contribute-docs/style-guide/formatting.md	428	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/formatting.md	444	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/grammar-spelling.md	12	Elastic.Wordiness	Consider using 'to' instead of 'In order to'.
contribute-docs/style-guide/grammar-spelling.md	18	Elastic.Wordiness	Consider using 'to' instead of 'In order to'.
contribute-docs/style-guide/grammar-spelling.md	20	Elastic.Wordiness	Consider using 'because' instead of 'since'.
contribute-docs/style-guide/grammar-spelling.md	28	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
contribute-docs/style-guide/grammar-spelling.md	35	Elastic.FirstPerson	Avoid first-person pronouns such as ' I, '.
contribute-docs/style-guide/grammar-spelling.md	35	Elastic.FirstPerson	Avoid first-person pronouns such as 'me'.
contribute-docs/style-guide/grammar-spelling.md	35	Elastic.FirstPerson	Avoid first-person pronouns such as 'my'.
contribute-docs/style-guide/grammar-spelling.md	35	Elastic.FirstPerson	Avoid first-person pronouns such as 'mine'.
contribute-docs/style-guide/grammar-spelling.md	40	Elastic.FirstPerson	Avoid first-person pronouns such as 'my'.
contribute-docs/style-guide/grammar-spelling.md	45	Elastic.Wordiness	Consider using 'because' instead of 'since'.
contribute-docs/style-guide/grammar-spelling.md	53	Elastic.FutureTense	'will and' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/grammar-spelling.md	53	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/grammar-spelling.md	53	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
contribute-docs/style-guide/grammar-spelling.md	73	Elastic.FutureTense	'it'll,' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/grammar-spelling.md	91	Elastic.FutureTense	'will make' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/grammar-spelling.md	309	Elastic.FutureTense	'You'll find' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/grammar-spelling.md	378	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/index.md	19	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	1	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	3	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	3	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/seo.md	7	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/seo.md	11	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	15	Elastic.Capitalization	'H1: Primary page title' should use sentence-style capitalization.
contribute-docs/style-guide/seo.md	23	Elastic.FutureTense	'will learn' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/seo.md	50	Elastic.FutureTense	'will be' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/seo.md	55	Elastic.Capitalization	'H2: Secondary headings' should use sentence-style capitalization.
contribute-docs/style-guide/seo.md	95	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	95	Elastic.FutureTense	'will help' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/seo.md	102	Elastic.FutureTense	'will learn' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/seo.md	113	Elastic.Acronyms	'CTR' has no definition.
contribute-docs/style-guide/seo.md	123	Elastic.Versions	Use 'and later' instead of 'and higher' when referring to versions.
contribute-docs/style-guide/seo.md	144	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/seo.md	151	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/seo.md	202	Elastic.FutureTense	'will depend' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/seo.md	210	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	214	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/seo.md	260	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	292	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	302	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	334	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	336	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/seo.md	365	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	379	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	389	Elastic.Wordiness	Consider using 'before' instead of 'Prior to'.
contribute-docs/style-guide/seo.md	390	Elastic.FutureTense	'will ignore' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/seo.md	406	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/seo.md	406	Elastic.DeviceAgnosticism	Use device-agnostic language when possible. Use 'select' instead of 'tap'.
contribute-docs/style-guide/seo.md	416	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	418	Elastic.Acronyms	'SEO' has no definition.
contribute-docs/style-guide/seo.md	422	Elastic.WordChoice	Consider using 'efficient' instead of 'simple', unless the term is in the UI.
contribute-docs/style-guide/seo.md	424	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/seo.md	434	Elastic.Acronyms	'USA' has no definition.
contribute-docs/style-guide/seo.md	451	Elastic.Wordiness	Consider using 'to' instead of 'in order to'.
contribute-docs/style-guide/ui-writing.md	11	Elastic.Acronyms	'EUI' has no definition.
contribute-docs/style-guide/ui-writing.md	32	Elastic.Wordiness	Consider using 'remove' instead of 'Eliminate'.
contribute-docs/style-guide/ui-writing.md	44	Elastic.Acronyms	'EUI' has no definition.
contribute-docs/style-guide/ui-writing.md	69	Elastic.WordChoice	Consider using 'efficient' instead of 'simple', unless the term is in the UI.
contribute-docs/style-guide/ui-writing.md	70	Elastic.FirstPerson	Avoid first-person pronouns such as ' I '.
contribute-docs/style-guide/ui-writing.md	86	Elastic.Acronyms	'RGB' has no definition.
contribute-docs/style-guide/ui-writing.md	111	Elastic.Acronyms	'APP' has no definition.
contribute-docs/style-guide/ui-writing.md	129	Elastic.Wordiness	Consider using 'impossible' instead of 'not possible'.
contribute-docs/style-guide/ui-writing.md	173	Elastic.FutureTense	'you'll find' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/ui-writing.md	188	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
contribute-docs/style-guide/ui-writing.md	192	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/ui-writing.md	205	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	18	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	18	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	29	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	29	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	40	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	40	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	44	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	66	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	82	Elastic.FutureTense	'you'll see' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/voice-tone.md	82	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	86	Elastic.Exclamation	Use exclamation points sparingly. Consider removing the exclamation point.
contribute-docs/style-guide/voice-tone.md	95	Elastic.FutureTense	'we'll help' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/voice-tone.md	101	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	116	Elastic.Exclamation	Use exclamation points sparingly. Consider removing the exclamation point.
contribute-docs/style-guide/voice-tone.md	156	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
contribute-docs/style-guide/voice-tone.md	176	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	189	Elastic.Acronyms	'ANN' has no definition.
contribute-docs/style-guide/voice-tone.md	191	Elastic.FutureTense	'will prevent' might be in future tense. Write in the present tense to describe the state of the product as it is now.
contribute-docs/style-guide/voice-tone.md	210	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	243	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	266	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	266	Elastic.WordChoice	Consider using 'efficient' instead of 'simple', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	266	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	268	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	274	Elastic.WordChoice	Consider using 'efficient' instead of 'simple', unless the term is in the UI.
contribute-docs/style-guide/voice-tone.md	278	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	278	Elastic.Ellipses	In general, don't use an ellipsis.
contribute-docs/style-guide/voice-tone.md	284	Elastic.Wordiness	Consider using 'to' instead of 'in order to'.
contribute-docs/style-guide/voice-tone.md	285	Elastic.Wordiness	Consider using 'if' instead of 'in the event that'.
contribute-docs/style-guide/voice-tone.md	286	Elastic.Wordiness	Consider using 'use' instead of 'utilize'.
contribute-docs/style-guide/voice-tone.md	286	Elastic.Wordiness	Consider using 'use' instead of 'make use of'.
contribute-docs/style-guide/voice-tone.md	287	Elastic.Wordiness	Consider using 'tell' instead of 'inform'.
contribute-docs/style-guide/voice-tone.md	287	Elastic.Wordiness	Consider using 'tell' instead of 'let know'.
contribute-docs/style-guide/voice-tone.md	288	Elastic.Wordiness	Consider using 'also' instead of 'in addition'.
contribute-docs/style-guide/voice-tone.md	290	Elastic.Wordiness	Consider using 'later' instead of 'at a later date'.
contribute-docs/style-guide/voice-tone.md	292	Elastic.Wordiness	Consider using 'allows' instead of 'provides the opportunity'.
contribute-docs/style-guide/voice-tone.md	301	Elastic.Wordiness	Consider using 'these' instead of 'All of these'.
contribute-docs/style-guide/voice-tone.md	305	Elastic.Exclamation	Use exclamation points sparingly. Consider removing the exclamation point.
contribute-docs/style-guide/voice-tone.md	307	Elastic.Wordiness	Consider using 'usually' instead of 'In most cases'.
contribute-docs/style-guide/voice-tone.md	319	Elastic.Wordiness	Consider using 'because' instead of 'Since'.
contribute-docs/style-guide/voice-tone.md	320	Elastic.Wordiness	Consider using 'when you' instead of 'The minute you'.
contribute-docs/style-guide/voice-tone.md	321	Elastic.Wordiness	Consider using 'watch the following tutorial' instead of 'Watch the following clip'.
contribute-docs/style-guide/voice-tone.md	322	Elastic.Wordiness	Consider using 'we recommend, we encourage' instead of 'Don't fall into the habit'.
contribute-docs/style-guide/voice-tone.md	338	Elastic.WordChoice	Consider using 'efficiently' instead of 'easily', unless the term is in the UI.

github-actions · 2025-11-24T15:19:29Z

🔍 Preview links for changed docs

contribute-docs/style-guide/accessibility.md

contribute-docs/good-issues.md

contribute-docs/style-guide/formatting.md

lcawl

There are quite a few broken bullet points in the grammar page

contribute-docs/style-guide/grammar-spelling.md

lcawl

I think there are some out-dated sections in the SEO gudelines

contribute-docs/style-guide/seo.md

lcawl

More broken bullets on the voice and tone page

contribute-docs/style-guide/accessibility.md

contribute-docs/style-guide/voice-tone.md

lcawl

More feedback on the UI writing page

contribute-docs/style-guide/ui-writing.md

Co-authored-by: Lisa Cawley <lcawley@elastic.co>

contribute-docs/style-guide/ui-writing.md

theletterf · 2025-11-25T16:18:45Z

@jmikell821 @natasha-moore-elastic @lcawl Please have another look — thanks! Feel free to edit directly on the branch.

leemthompo · 2025-11-27T13:34:54Z

contribute-docs/how-to/good-issues.md

+navigation_title: Create good issues
+---
+
+# How to create good docs issues


might this nest nicely under the how-to section?

leemthompo

I have some high-level comments, some of which we should think about planning in follow-ups, notably a cheat sheet that extracts the super critical info from each section.

I think it's valuable to get this out there in a public URL sooner rather than later and we should aim to get this merged by end of next week— once everybody who's interested has a chance to review, after the thanksgiving break.

I didn't systematically re-read every page, but my comments about linking to Vale in the weeds applies to any page where we can link to tooling information and say "you don't really need to commit this stuff to memory"

leemthompo · 2025-11-28T11:00:44Z

contribute-docs/style-guide/seo.md

@@ -0,0 +1,452 @@
+# SEO guidelines


What's good for SEO is basically what's good for a human reader too, I wonder if shouldn't subtly reorient this towards "Best practices for structuring your pages". We should all be referring to this and absorbing it into our muscle memory over time!

I think this page is one of the most useful and immediately practical for all docs contributors, so I wonder if it might be buried and lost a bit in the style guide section.

To my eyes, ideally it would be a sibling to how to create good issues and how to write cumulative docs. 🤔

But maybe that's something we can think about in a follow-up.

leemthompo · 2025-11-28T11:07:34Z

contribute-docs/style-guide/index.md

+navigation_title: Style guide
+---
+
+# Technical writing style guide


I think this entire section is a great systematic reference for docs contributors, principally the docs team, and therefore it's valuable in itself to just get it out there into an easy-to-find URL.

By the same token, it's super information dense and veers into the much-feared guidelines bloat territory. To remedy this, I think it would be a super useful exercise to extract the 2-3 essentials from each page and then combine them into a cheat sheet or quick reference.

I think this is important because we don't expect the majority of contributors to read these pages exhaustively, but we want to surface the critical info from each page in a digestible way.

I wouldn't expect this to happen in this PR of course :)

+CC @jmikell821 for the follow-up.

leemthompo · 2025-11-28T11:17:48Z

contribute-docs/style-guide/word-choice.md

+description: Recommendations for choosing the right words in your documentation.
+---
+
+# Word choice


Is this in sync with Vale? I'd link to Vale here too and explain that you don't need to commit this to memory if you're using it

leemthompo · 2025-11-28T11:19:38Z

contribute-docs/style-guide/seo.md

+  * Start paragraphs with key information and use plain language for clarity.  
+  * Use formatting tools (bold, italics, code formatting) to highlight important terms or actions.
+
+### Lists


this overlaps with formatting.md where we also talk about lists, not sure if want to use a snippet here or reduce one to a link to the other 🤷

leemthompo · 2025-11-28T11:21:18Z

contribute-docs/style-guide/grammar-spelling.md

+description: Guidelines for using correct grammar and spelling in your writing.
+---
+
+# Grammar and spelling


I would have a callout here that Vale will flag most of this stuff for you, and you don't need to commit this to memory or reference it ahead of time if you don't want to

theletterf added 5 commits November 24, 2025 15:53

Add style guide files

558eba3

Edits

7ab2817

Add good issues

6e75e15

Remove section

f85899a

Tweak titles

dcf7102

theletterf requested a review from a team as a code owner November 24, 2025 15:16

github-actions bot deployed to docs-preview November 24, 2025 15:17 View deployment

lcawl reviewed Nov 24, 2025

View reviewed changes

contribute-docs/style-guide/accessibility.md Outdated Show resolved Hide resolved

contribute-docs/style-guide/voice-tone.md Outdated Show resolved Hide resolved

contribute-docs/style-guide/voice-tone.md Outdated Show resolved Hide resolved

lcawl reviewed Nov 24, 2025

View reviewed changes

lcawl added 9 commits November 24, 2025 13:12

Update contribute-docs/style-guide/ui-writing.md

f780ef6

Update contribute-docs/good-issues.md

8db798a

Update contribute-docs/style-guide/accessibility.md

8bb4f0a

Update contribute-docs/style-guide/formatting.md

8623bec

Update contribute-docs/style-guide/formatting.md

2dd56b6

Update contribute-docs/style-guide/formatting.md

0513139

Update contribute-docs/style-guide/formatting.md

1b311e3

Update contribute-docs/style-guide/formatting.md

a8c6d4b

Update contribute-docs/style-guide/formatting.md

e38352f

github-actions bot had a problem deploying to docs-preview November 24, 2025 21:16 Failure

lcawl added 3 commits November 24, 2025 13:16

Update contribute-docs/style-guide/formatting.md

ae082f5

Update contribute-docs/style-guide/formatting.md

2ac87b1

Update contribute-docs/style-guide/formatting.md

2e65820

github-actions bot had a problem deploying to docs-preview November 24, 2025 21:18 Failure

lcawl added 2 commits November 24, 2025 13:19

Update contribute-docs/style-guide/seo.md

ad990df

Update contribute-docs/style-guide/seo.md

61ba162

github-actions bot deployed to docs-preview November 24, 2025 22:24 View deployment

Fix formatting in ui-writing.md

7de9b15

github-actions bot deployed to docs-preview November 24, 2025 22:31 View deployment

More edits

3320595

github-actions bot deployed to docs-preview November 24, 2025 23:12 View deployment

Update contribute-docs/style-guide/seo.md

a3dfb46

github-actions bot deployed to docs-preview November 24, 2025 23:15 View deployment

Apply suggestions from code review

e949062

Co-authored-by: Lisa Cawley <lcawley@elastic.co>

github-actions bot deployed to docs-preview November 25, 2025 07:36 View deployment

Edits

18cfe23

github-actions bot deployed to docs-preview November 25, 2025 09:37 View deployment

theletterf commented Nov 25, 2025

View reviewed changes

contribute-docs/style-guide/ui-writing.md Outdated Show resolved Hide resolved

florent-leborgne mentioned this pull request Nov 25, 2025

Update UI naming guidelines to match new Kibana chrome #4073

Open

Remove UI naming sections

a5c9e98

github-actions bot deployed to docs-preview November 25, 2025 10:56 View deployment

Remove indentation

b8f5d4e

theletterf requested a review from lcawl November 25, 2025 10:58

github-actions bot deployed to docs-preview November 25, 2025 10:59 View deployment

theletterf requested review from jmikell821 and natasha-moore-elastic November 25, 2025 14:06

More minor edits

9e28de3

github-actions bot deployed to docs-preview November 26, 2025 21:21 View deployment

theletterf added 2 commits November 27, 2025 13:55

Remove keywords section

09ee8fd

Merge branch 'main' into add-style-guide

451be67

github-actions bot deployed to docs-preview November 27, 2025 12:56 View deployment

leemthompo reviewed Nov 27, 2025

View reviewed changes

Move good issues

ecc51b6

github-actions bot deployed to docs-preview November 27, 2025 14:58 View deployment

leemthompo reviewed Nov 28, 2025

View reviewed changes

Add style guide to Contribute to the docs #4060

Are you sure you want to change the base?

Add style guide to Contribute to the docs #4060

Conversation

theletterf commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Generative AI disclosure

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lcawl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lcawl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lcawl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lcawl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

theletterf commented Nov 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo left a comment

theletterf commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading