[PROPOSAL] Move config descriptions from falco.yaml to Falco documentation

[Andreagit97]

What to document

At every new config added, the falco.yaml becomes bigger, this is because we add very detailed descriptions...this is good of course but it decreases the readability of the falco.yaml. What about moving the config descriptions inside our documentation and removing them from falco.yaml. Maybe we could just leave a brief description of 2 lines... WDYT? @falcosecurity/falco-maintainers ?

[leogr]

How can we keep them in sync during the 4 months dev cycles?

(just thinking out loud)
Perhaps we can create a .MD file in the Falco repo, and sync to the website close to the release 🤔

[FedeDP]

While i definitely agree that the falco.yaml is growing way too big, i think that having the descriptions separated (even worse, on a website, not locally) from the local config file is a bit messy and would waste quite a bit of adopters' time.
I would love to hear what other maintainers think about this one though!

[incertum]

I also believe it should be kept within the file. If we worry about it being cumbersome to scroll down, we could move all configs up and instead have all descriptions in the same order following the configs? Would this address the primary concerns raised?

[FedeDP]

we could move all configs up and instead have all descriptions in the same order following the configs?

I like this; simple and effective! Perhaps we can also re-organize top level keys (eg: the new falco-libs top level key proposed here: #3071)

[Andreagit97]

we could move all configs up and instead have all descriptions in the same order following the configs? Would this address the primary concerns raised?

Yeah, probably it could improve the readability!

[leogr]

Maybe we can have just a short description close to the relevant setting, and long descriptions at the end of the file

[incertum]

Maybe we can have just a short description close to the relevant setting, and long descriptions at the end of the file

Works, a one-liner TLDR and the more verbose description below. SGTM!

[poiana]

Issues go stale after 90d of inactivity.

Mark the issue as fresh with /remove-lifecycle stale.

Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Provide feedback via https://github.com/falcosecurity/community.

/lifecycle stale

[Andreagit97]

/remove-lifecycle stale

[poiana]

Issues go stale after 90d of inactivity.

Mark the issue as fresh with /remove-lifecycle stale.

Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Provide feedback via https://github.com/falcosecurity/community.

/lifecycle stale

[Andreagit97]

/remove-lifecycle stale

[FedeDP]

An idea: we could add a man page for Falco and move there all the config options + CLI options descriptions.

[leogr]

An idea: we could add a man page for Falco and move there all the config options + CLI options descriptions.

@FedeDP could you give us an example, please? 🙏