Skip to content

Conversation

@wajihaparvez
Copy link
Contributor

@wajihaparvez wajihaparvez commented Nov 17, 2025

This PR restructures the AutoOps section + makes various general fixes. Most notably, I have:

  • moved the Views and Events pages under the AutoOps for ECH section and linked to them from the AutoOps for SM clusters section because they don't apply to AutoOps for Serverless. I'm open to feedback if anyone has a better idea for organizing this info.
  • added a child to the Troubleshooting page because it had too much info. More child pages will be added in the future.

Closes #3559 and #3220

…wajihaparvez/docs-content into enhance-and-restructure-autoops-section
@github-actions
Copy link

github-actions bot commented Nov 21, 2025

Vale Linting Results

Summary: 3 warnings, 24 suggestions found

⚠️ Warnings (3)
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.

Copy link
Collaborator

@shainaraskas shainaraskas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. don't love self-managed for 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.

  2. 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
    	* faq
    

    or

    * autoops
    	* set up ech
    	* set up ccm
    	* serverless
    	* insights 
    		* ech/ccm
    		* serverless
    	* regions
    	* faq
    

    or

    * autoops
    	* set up ech
    	* set up ccm
    	* serverless
    	* insights ech/ccm
    	* insights serverless
    	* regions
    	* faq
    

@wajihaparvez
Copy link
Contributor Author

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:

  • There is no setting up required for ECH and Serverless, only how to access (but the instructions for both are different)
  • Setting up is required for self-managed (Cloud Connect) with different sets of instructions for prod and local dev
  • The "insights" are the same for ECH and Self-managed (Views and Events) but different for Serverless (Search tier and Search AI lake + more coming soon)
  • Regions and FAQ are common for all deployment types

So if we split into config and consumption, it would have to be more like:

* Autoops
   * How to access
     * in ech
     * in serverless
   * Set up in self-managed
     * prod
     * local dev
     * troubleshooting
   * Events in ech and self-managed
   * Views
     * ech and self-managed
     * serverless
    * regions
    * faq
 * Intro and explanation of AutoOps for serverless??
 * Intro and explanation of AutoOps for self-managed??

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🔧

@shainaraskas
Copy link
Collaborator

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.

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

There is no setting up required for ECH and Serverless

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

* autoops (overview + comparison info, with a setup section that explains no setup is needed for serverless/ech)
	* set up for ccm
	* insights (access instructions for all deployment types could go here)
		* ech/ccm views and events
		* serverless views (billing dimensions info goes here)
	* regions
	* faq

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Restructure AutoOps section

2 participants