Add troubleshooting content type guidelines#4512
Add troubleshooting content type guidelines#4512alexandra5000 merged 12 commits intoelastic:mainfrom
Conversation
Vale Linting ResultsSummary: 1 warning, 2 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| contribute-docs/content-types/_snippets/templates/troubleshooting-template.md | 137 | Elastic.DontUse | Don't use 'Just'. |
💡 Suggestions (2)
| File | Line | Rule | Message |
|---|---|---|---|
| contribute-docs/content-types/_snippets/templates/troubleshooting-template.md | 130 | Elastic.Wordiness | Consider using 'all' instead of 'all of '. |
| contribute-docs/content-types/troubleshooting.md | 23 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
The Vale linter checks documentation changes against the Elastic Docs style guide.
To use Vale locally or report issues, refer to Elastic style guide for Vale.
🔍 Preview links for changed docs |
contribute-docs/content-types/_snippets/templates/troubleshooting-template.md
Show resolved
Hide resolved
contribute-docs/content-types/_snippets/templates/troubleshooting-template.md
Show resolved
Hide resolved
|
was the old guidance mined before this PR was created? lots in there, especially around error messages |
|
@shainaraskas Thanks! I made some updates based on the old guide. |
KOTungseth
left a comment
There was a problem hiding this comment.
This is a strong foundation with clear intent, well aligned with how Elastic users consume troubleshooting content, and appropriately prescriptive.
I left some suggestions for making the content more operational for contributors.
contribute-docs/content-types/_snippets/templates/troubleshooting-template.md
Show resolved
Hide resolved
contribute-docs/content-types/_snippets/templates/troubleshooting-template.md
Show resolved
Hide resolved
contribute-docs/content-types/_snippets/templates/troubleshooting-template.md
Show resolved
Hide resolved
|
This looks great! Nice work @alexandra5000, I'm no troubleshooting expert so I'm not really qualified to approve this, but I think with @theletterf and @KOTungseth's suggestions this will be in good shape |
|
fwiw, support was VERY passionate about us having this additional resources/contact/working with support boilerplate on entrypoints, especially because half of our troubleshooting content is in the support portal https://stunning-adventure-qrvr1k2.pages.github.io/content-types/troubleshooting/ |
…roubleshooting template
…roubleshooting-template
|
@shainaraskas Very good point, thank you for reminding me about it. I even discussed adding a dedicated "Contact support" page to every troubleshooting folder/section. As of today, a dedicated page exists in some of them, so I included that info as well. |
Summary
This PR introduces a new "Troubleshooting" content type with detailed guidelines for creating effective troubleshooting pages in the Elastic documentation. Additionally, a template for troubleshooting pages is added. Updates to the content types
index.mdfile are also made to include the new troubleshooting section.Closes #115
Generative AI disclosure
To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following:
Tool(s) and model(s) used:
Some edits with Claude Sonnet 4.5 using Cursor