[tracking] Improve code documentation

sgaist commented 6 months ago

This ticket is a follow up of today's community meeting (and heavily inspired from https://github.com/falcosecurity/libs/issues/1747.

TLDR: improve the code base documentation so that new (and old) contributors have an easier time going through it.

The longer story: while the falco code base is not void of documentation, it's also not completely documented and there are often a mix of doxygen and documentation formatted as comments (not related to comments in code). This make understanding how things are working more complicated than needed.

While the application itself is not a library to be used by others, the people wanting to work on the code would benefit from having it better documented. This helps working on bug fixes and features without requiring to read through all the implementation to understand how things are used.

There are several (complimentary) ways that this could be achieved:

Each time someone modifies a function that is not yet documented, add it
Each time a new API is added, mandatory document it
Have documentation sprints where people gather to do just that: take the time to document

This does not need to be the work of a single person.

One thing that could be done in that context is the creation of a group/team of people interested in this topic. They could help plan out the work on the long term, prepare guidelines, help review submission (style is as important as accuracy), etc. This would allow to have a consistent work done through all the Falco projects.

incertum commented 6 months ago

Fully supportive, see also my comment in the libs equivalent ticket https://github.com/falcosecurity/libs/issues/1747#issuecomment-1997893695.

sgaist commented 6 months ago

As an example of something that should be part of the contributor documentation: https://falco.org/blog/intro-development-falco/ The simple trick for using a local checkout of falcosecurity/libs is very handy when one wants to prepare a new feature for falco based on unreleased changes in libs and I think should be part of a "Getting started to hack on Falco" document which is different from "Building Falco from sources".

poiana commented 3 months ago

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

incertum commented 3 months ago

/remove-lifecycle stale

poiana commented 1 week ago