Dasharo Security options deserve an extensive section with each feature separated

[macpijan]

We have quite a lot such features already. Each of them should be described independently, not all of them in a single section like here: https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#dasharo-security-options

[miczyg1]

When the documentation has been written, there was no possibility to get an entry into the TOC if the heading was at level 2 (###), so one couldn't nest it properly. Is it possible to enable TOC generation for headings lower than level 2?

[pietrushnic]

@miczyg1 there is no need for TOC generation. Links can be created without TOC. Please take a look at DTS:

• Features with in-text-toc (no entries in menu)
• In page link to given section HCL report

[miczyg1]

In the example above how would you link to HCL Report correctness if you wish to?

Hirerarchy of heading should be preserved to reflect the nesting of options. And if the level of heading is too low then links are not generated via rendered docs. So one has to create markdown link with []() syntax in some self-made pseudo-TOC in markdown instead of automatic generation by mkdocs. Doesn't look efficient, that's what I am trying to say.

[pietrushnic]

@miczyg1

In the example above how would you link to HCL Report correctness if you wish to?

https://docs.dasharo.com/dasharo-tools-suite/documentation/#hcl-report-correctness

Hirerarchy of heading should be preserved to reflect the nesting of options. And if the level of heading is too low then links are not generated via rendered docs. So one has to create markdown link with []() syntax in some self-made pseudo-TOC in markdown instead of automatic generation by mkdocs. Doesn't look efficient, that's what I am trying to say.

That is not mandatory, this is one of the solutions that DTS applied. You can link without having potentially redundant subsection TOC. Linking to any header is possible, but those headers may be not present on the right-side menu and that is not an issue. IMHO explanation of features should be behind some headers because those are linkable not like bullet points. Let's improve documentation.

[miczyg1]

@miczyg1

In the example above how would you link to HCL Report correctness if you wish to?

https://docs.dasharo.com/dasharo-tools-suite/documentation/#hcl-report-correctness

Hirerarchy of heading should be preserved to reflect the nesting of options. And if the level of heading is too low then links are not generated via rendered docs. So one has to create markdown link with syntax in some self-made pseudo-TOC in markdown instead of automatic generation by mkdocs. Doesn't look efficient, that's what I am trying to say.

That is not mandatory, this is one of the solutions that DTS applied. You can link without having potentially redundant subsection TOC. Linking to any header is possible, but those headers may be not present on the right-side menu and that is not an issue. IMHO explanation of features should be behind some headers because those are linkable not like bullet points. Let's improve documentation.

And still they are not linkable from the rendered view. Imagine community member wanting to link to given section but oops... it doesn't work/nowhere to be seen... :upside_down_face: Manual link creation by adding #hcl-report-correctness, as you have shown above, is not quite user-friendly. For whom do we make the docs.dasharo.com in the first place? Rather not for Dasharo Team. Let's not expect everyone knows markdown or mkdocs internals to do such a simple thing, please.

[pietrushnic]

And still they are not linkable from the rendered view. Imagine community member wanting to link to given section but oops... it doesn't work/nowhere to be seen... 🙃 Manual link creation by adding #hcl-report-correctness, as you have shown above, is not quite user-friendly. For whom do we make the docs.dasharo.com in the first place? Rather not for Dasharo Team. Let's not expect everyone knows markdown or mkdocs internals to do such a simple thing, please.

And what?

I'm not sure what this argument proves. We can improve user experience, improve the marketability of new features, and save ourselves time. Instead of that, we argue about not doing that. because of some hypothetical scenario. The current alternative is not acceptable because new features are lost in bigger sections of the documentation.

Let's stop the discussion and fix the documentation so we can link to particular sections. That is the goal of this issue.