-
Notifications
You must be signed in to change notification settings - Fork 181
Enhance and restructure AutoOps pages #3955
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Enhance and restructure AutoOps pages #3955
Conversation
…wajihaparvez/docs-content into enhance-and-restructure-autoops-section
Vale Linting ResultsSummary: 3 warnings, 24 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 84 | Elastic.DontUse | Don't use 'and/or'. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 118 | Elastic.Latinisms | Latin terms and abbreviations are a common source of confusion. Use 'using' instead of 'via'. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 149 | Elastic.Latinisms | Latin terms and abbreviations are a common source of confusion. Use 'using' instead of 'via'. |
💡 Suggestions (24)
| File | Line | Rule | Message |
|---|---|---|---|
| deploy-manage/monitor/autoops.md | 53 | Elastic.Wordiness | Consider using 'because' instead of 'since'. |
| deploy-manage/monitor/autoops.md | 55 | Elastic.Capitalization | 'How AutoOps is licensed' should use sentence-style capitalization. |
| deploy-manage/monitor/autoops.md | 57 | Elastic.Acronyms | 'ECU' has no definition. |
| deploy-manage/monitor/autoops.md | 65 | Elastic.Capitalization | 'What AutoOps monitors [ec_autoops_scope]' should use sentence-style capitalization. |
| deploy-manage/monitor/autoops/autoops-for-cloud-hosted.md | 12 | Elastic.Capitalization | 'AutoOps for' should use sentence-style capitalization. |
| deploy-manage/monitor/autoops/autoops-for-cloud-hosted.md | 18 | 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. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 25 | Elastic.Semicolons | Use semicolons judiciously. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 78 | Elastic.FutureTense | 'will return' might be in future tense. Write in the present tense to describe the state of the product as it is now. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 82 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 86 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 87 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'Disable', unless the term is in the UI. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 87 | Elastic.Acronyms | 'XGET' has no definition. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 87 | Elastic.Acronyms | 'XGET' has no definition. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 92 | Elastic.FutureTense | 'will stop' might be in future tense. Write in the present tense to describe the state of the product as it is now. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 123 | Elastic.FutureTense | 'will attempt' might be in future tense. Write in the present tense to describe the state of the product as it is now. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 129 | Elastic.FutureTense | 'will use' might be in future tense. Write in the present tense to describe the state of the product as it is now. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 129 | Elastic.Acronyms | 'CSP' has no definition. |
| deploy-manage/monitor/autoops/autoops-sm-troubleshoot-firewalls.md | 129 | Elastic.Acronyms | 'CSP' has no definition. |
| deploy-manage/monitor/autoops/cc-cloud-connect-autoops-troubleshooting.md | 42 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| deploy-manage/monitor/autoops/ec-autoops-faq.md | 61 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| deploy-manage/monitor/autoops/ec-autoops-faq.md | 109 | Elastic.FirstPerson | Avoid first-person pronouns such as ' I '. |
| deploy-manage/monitor/autoops/ec-autoops-faq.md | 109 | Elastic.FirstPerson | Avoid first-person pronouns such as 'my'. |
| deploy-manage/monitor/autoops/use-autoops-in-sm-cluster.md | 17 | Elastic.Capitalization | 'Views in AutoOps' should use sentence-style capitalization. |
| deploy-manage/monitor/autoops/use-autoops-in-sm-cluster.md | 21 | Elastic.Capitalization | 'Events in AutoOps' should use sentence-style capitalization. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
-
don't love
self-managedfor ECK and ECE. I know these pages have been around for a while, but these deployment types operate so differently from each other in most cases that they really rarely should be grouped together, so we don't use a grouped term for them in docs even though one exists internally. -
I don't agree with nesting views / events under ECH because cloud connected folks will never find them. my recommendation is splitting this content into config and consumption, and having subsections for the different deployment types, e.g.
* autoops * set up * ECH * cloud connected * serverless * autoops insights (or some sort of combo term) * ECH + CCM * serverless * regions * faqor
* autoops * set up ech * set up ccm * serverless * insights * ech/ccm * serverless * regions * faqor
* autoops * set up ech * set up ccm * serverless * insights ech/ccm * insights serverless * regions * faq
|
Thanks @shainaraskas! About the nesting/structure, I get your concern. That's why I added the Use AutoOps in your self-managed cluster page to lead cloud connect/self-managed users there. Another option was to duplicate the pages, but I wanted to avoid duplication. The problem with splitting the pages into config and consumption is that there's too much variation between the different deployment types:
So if we split into config and consumption, it would have to be more like: For someone who's using just one deployment type, that's a lot of jumping around for info. Plus, it feels like we're reshuffling all the pages and potentially introducing more confusion just because we want the Views and Events pages to show up in both the ech and self-managed sections. That's why I feel like keeping all the deployment types + their respective docs separate makes all of this easier to navigate. However, I've been staring at these pages for wayyy too long so it's possible I've grown accustomed to the separate deployment type model. If my proposed structure above makes more sense to fresh eyes, I'm happy to move things around🔧 |
I think ultimately it's still something that should do - nesting this info inside of one deployment type when it applies to many (especially because it's actually the most "active" content - stuff people who use autoops all the time need to refer to) is burying it. I think something like this that pulls the insights into buckets so serverless people aren't confused is a lighter touch, and keeps info about day to day usage front and center. I also think that explaining that serverless analyzes vcu vs hosted/ccm more about resource utilization is nice content for the autoops overview, and the guts of the billing dimension info could go into the serverless insights intro
sounds like we could go even lighter here then - this is just wayfinding - why do we have dedicated pages? your self-managed cluster access instructions are also buried pretty deeply for day-to-day usage. here's kind of where i'm going based on looking at the content a second time ultimately, I won't block your approach because this isn't really my content, and I realize I'm throwing a lot at you. however, I think designing the info hierarchy based on modes of usage and info people need at each stage would likely be a worthy effort. let me know if you want to talk synchronously about this or just leave it alone and let you do your thing. |
This PR restructures the AutoOps section + makes various general fixes. Most notably, I have:
Closes #3559 and #3220