update(docs): improve information in the configuration docs

[VladMasarik]

Proposed Changes

• Docs suggestions. When I was trying to setup docs, I had to use the online docs, and finding out anything was an awful pain especially because I had to search through the code.

I did not create an issue first because having something concrete to comment about is faster than explaining my suggestions, and then implementing them. The PR is of course not final, I would like to first know you thoughts, improvements, and I have a few questions. When all is done, I would adjust the JSON, TOML etc. parts as well.

Questions:

• Why is the section "Using commands on scanned files as comments" in "Running KICS" rather than configuration section?
• Does verbse flag work? When we set it verbose=false there was no difference with verbose=true that we could see.
• type: "type of queries to use in the scan" does that require list of queries?

I submit this contribution under the Apache-2.0 license.

[VladMasarik]

Also, I am happy to do more changes in the docs in this PR if consistency with other docs would be an issue, just let me know.

[rafaela-soares]

Hello, @VladMasarik!

Thank you so much for using KICS and also contributing 🚀

You can find a more detailed documentation about the scan flags here.

[VladMasarik]

You can find a more detailed documentation about the scan flags here.

Oh so that is where all the explanations are! Completely my opinion, but wouldn't it be better to have this information in the configuration part as well? Or at least I think that a link in the configuration saying ... "Full configuration options can be found in CLI, and if you want to disable kics in some parts of files see Running KICS", would immensely help. I would say duplicating the information would be good as well, but I don't think it is worth the extra maintenance from your side.

Also, another topic would be could KICS have only docs for actually "getting started" in the getting started section? Rather than basically all the docs? Eg. I would expect maybe installation, running KICS examples and references to the actual configuration, and how to read results than all this:

Then again I think this would be too much conversation in a single PR.

[rafaela-soares]

You can find a more detailed documentation about the scan flags here.

Oh so that is where all the explanations are! Completely my opinion, but wouldn't it be better to have this information in the configuration part as well? Or at least I think that a link in the configuration saying ... "Full configuration options can be found in CLI, and if you want to disable kics in some parts of files see Running KICS", would immensely help. I would say duplicating the information would be good as well, but I don't think it is worth the extra maintenance from your side.

We totally agree with you! The configuration documentation should be definitely improved. We can present an example of a configuration and refer the command's doc as you suggested. Do you mind updating?

I would like to thank you for noticing, taking the time to contribute, and give your feedback.

Also, another topic would be could KICS have only docs for actually "getting started" in the getting started section? Rather than basically all the docs? Eg. I would expect maybe installation, running KICS examples and references to the actual configuration, and how to read results than all this:

We will discuss this matter with the Product Manager. As soon as we have some decision, I will let you know. Once again, thank you so much for your feedback 🚀

Then again I think this would be too much conversation in a single PR.

You can use the GitHub discussions or contact us via [email protected], if you want 😊

[VladMasarik]

I have added all the changes that I have "imagined". Let me know what you think, and what would need to be adjusted. 👍

[rafaela-soares]

Thank you so much, @VladMasarik! It seems great!

Regarding the "Getting Started" section on the website, we will try to take care of it as soon as possible. We agree that should be improved. Thank you so much for the suggestion!

[rafaela-soares]

Does verbose flag work? When we set it verbose=false there was no difference with verbose=true that we could see.

@VladMasarik, yes. The verbose flag gives information about the logs (WRN, INF, ...). If you need help with that, let me know. For example:

With -v:

[VladMasarik]

@rafaela-soares

Regarding the "Getting Started" section on the website, we will try to take care of it as soon as possible.

I dont think you need to rush it, but it was somewhat confusing to see all of the documentation in the "Getting Started" section.

The verbose flag gives information about the logs (WRN, INF, ...). If you need help with that, let me know. For example:

Maybe I was making a mistake somewhere, but I could swear that I still saw these WARN messages. Although, we did enable only WARN and above warning messages.

Still thank you for such a quick responses!