search

coreruleset / documentation

CRS Documentation
https://coreruleset.org/docs/
4 stars 20 forks source link

Idea: restructuring the hierarchy for presentation and the uses #133

Open dextermallo opened 4 months ago

dextermallo commented 4 months ago

Hi CRS Teams 👋

This idea bumps into my mind when I am trying to learn what is new in CRS 4.0. For CRS 4.0, one of the key features is the plugin. Also, many new repositories are coming up to the organizations. I tried to understand what they functioning for, so I did a category for the current repositories:

Which shows the growth of plugins. Also, there are many repositories worth mentioning in the documentation (such as testing utilities). I am thinking of making the documentation structure more intuitive - both beginner and advanced users/contributors can find what they need in one glance.

Specific, main changes include:

  1. Rephrase the main sections: 1.1. Getting Started: The beginner's go-to. Should have a tutorial about the basics, and the setup of how to run CRS. 1.2. How CRS Works: The fundamentals/concepts of CRS. 1.3. About Rules: Explain rules (schema, type, etc.) 1.4. About Plugins: Introduce the use of plugins. 1.5. Advanced Usages: Advanced contents aside from the Section 1.1. Getting Started, including advanced settings, other services' integrations, etc. 1.6. Development: About developing rules, testing, dev utilities, etc. 1.7. Known Issues: The go-to for troubleshooting. 1.8. Additional Resources
  2. Merge duplicated / related pages.

Here is the proposed structure:

Home
├── 1. Getting Started
│   ├── CRS Installation                (rename Installing CRS, merge Extended Install)
│   ├── Using Containers                (moved)
│   ├── Upgrade CRS Versions            (extract from Installation)
│   └── Compatible Integrations             (rename Engine and Integration Options) 
│   
├── 2. How CRS Works
│   ├── Anomaly Scoring
│   ├── Paranoia Levels
│   ├── False Positive and Tuning
│   └── Sampling Mode
│
├── 3. About Rules                          
│   ├── Rule IDs
│   ├── What is In The Rules            (rename: Rules)
│   ├── Making Rules                (rename, merge Writing Rules)
│   └── Metadata
│
├── 4. About Plugins
│   ├── Introduction                (rename: Plugin Mechanism)
│   ├── Available Plugins               (new)
│   └── Writing Plugins             (moved)
│
├── 5. Advanced Usages
│   ├── Kubernetes Ingress Controllers
│   ├── Self-Contained Mode
│   └── Log Handling
│
├── 6. Development
│   ├── Contribution Guidelines
│   ├── Testing the Rule Set            (moved)
│   ├── Asembling Regular Expressions
│   ├── Dev Tools                   (rename Useful Tools, merge crs-toolhain)
│   └── CRS Sandbox
│
├── 7. Known Issues
│
└── 8. Additional Resources
theseion commented 4 months ago

Thanks for taking the initiative @dextermallo. To me, your idea sounds great. The documentation could definitely use some love. Let's from our resident technical writer @RedXanadu what he thinks.

dune73 commented 4 months ago

The overview of the existing repos is very helpful. I am afraid to lose the perspective as well.

As long as you do not initiate a big rewrite of the documentation, shuffling around items makes sense. Namely getting the installation simplified. And I like how you move the containers into the installation.

But then I liked the section "operation" and the idea behind it (even if not completely implemented). Your section titles are much more conceptual and lack this hands-on guidance.

But it's a worthwhile initiative nevertheless.

Would you be available to discuss this in our issue meeting next week Monday? 20:30 CEST is not the best timing for you, I dare say ...

dextermallo commented 3 months ago

But then I liked the section "operation" and the idea behind it (even if not completely implemented). Your section titles are much more conceptual and lack this hands-on guidance.

Yeah, I do agree the term operations can cover more in-depth concepts in the documentation, perhaps that can be another title for the section Advanced Usages.

Would you be available to discuss this in our issue meeting next week Monday? 20:30 CEST is not the best timing for you, I dare say ...

I will try my best if I can stay awake at that moment... 🤣. Or I will put some inputs earlier on Slack

dextermallo commented 3 months ago

Hi Teams, any input for this? Or anything I could address?

theseion commented 3 months ago

I suggest, you create a PR, where we you set up the new structure. Don't focus on details yet, simply move pages around. Then we can discuss how it looks in that PR (everyone will be able to preview your idea because we can render the page locally). Once everyone agrees on the structure, we can go from there.