aquasecurity
docs: improve targets documentation
Description
- define target types and refer to them in relevant places
- use consistent structure for all targets docs (also simplify it)
- (also update scanner embedding doc)
Related issues
- https://github.com/aquasecurity/trivy/discussions/1891
some clarifications about the target docs structure:
- start with general description of the target
- clearly classify the target pre/post scan
- include general usage example the covers supported arguments
- state supported scanners, and default scanners for the target
- cover additional flags and options
removed some sections/examples that appeared in some of the target and were redundant IMO for the image scanning specifically, I decided to demote the image config section as it is no so popular and wasn't consistent with the structure, I documented it like all the other flags. Also I wasn't sure the podman detailed description was necessary but left it
Since this PR contains many changes, what if splitting it into some PRs? For example, docs/docs/advanced/container/embed-in-dockerfile.md, docs/docs/coverage/language/index.md. docs/docs/index.md, etc, don't seem to be blocked by other changes.
the common between all those changes is they all need to refer to the "pre/post build" section that was added in this PR.
BTW, I think that the targets documentation grew too verbose overtime, and became not so much readable. It's not a bad thing, it's a natural process but every once in a while we can groom the docs to make them more pleasent to read. I think that less is more in this case, and by removing redundant information and keeping tidy structure it became a bit more easy to consume.
This PR includes a large number of changes, with many lines being deleted in particular. It's quite difficult to thoroughly verify that nothing important has been removed. I've reviewed it several times, but I'm still not fully confident. Especially for documentation, since there are no tests, we have to rely on manual checks. So, how about splitting this PR into smaller parts and merging them one by one once each part is confirmed to be fine? That way, we can avoid major context switches each time and keep discussions focused, which I believe would make the process smoother.
I understand it's hard to follow, but do we really need to? 1) my goal was actually to remove some of the redundant text. it's easy to add a "tip" and "note" every time a user asks a question. but over time, this grows into something unreadable. my goal is to create a shorter doc (which still contains all the info) not a longer doc. 2) this isn't an incremental change but a complete rewrite. like in a code rewrite, we want to see that the end results makes sense, not that every function has a matching one.
https://github.com/aquasecurity/trivy/pull/8305#issuecomment-2730488760
Of course, I agree that documentation that has become unnecessarily long and hard to read should be streamlined and that it’s not essential to retain every detail. However, I’ve already seen several instances (example) where, due to a lack of context—context that only those deeply involved in the implementation possess—sections were considered unnecessary and removed. I think these removals should be reviewed carefully by developers who are familiar with that domain.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
I think there's still value in this PR, but perhaps it's not top priority at the moment