search

kubewarden / docs

Kubewarden's documentation
https://docs.kubewarden.io
Creative Commons Attribution 4.0 International
13 stars 23 forks source link

Infrastructure for implementing a Kubewarden controlled vocabulary. #396

Closed jhkrug closed 4 months ago

jhkrug commented 5 months ago

docusaurus.config.js defines a preprocessor which replaces all instances of the variables defined in ./variables.json with their values. See the changes in quick-start.md for an example. `[[< policy-server-component >]]' to 'PolicyServer'.

Part of #394.

netlify[bot] commented 5 months ago

Deploy Preview for silly-bunny-8cedd0 ready!

Name Link
Latest commit a094e92ea317e43757c0bb0c5e7baab0c53d0612
Latest deploy log https://app.netlify.com/sites/silly-bunny-8cedd0/deploys/664f45bb1e8f3800088085b4
Deploy Preview https://deploy-preview-396--silly-bunny-8cedd0.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

jhkrug commented 5 months ago

Added some review comments.

Could the policy-server-component variable for "PolicyServer" link to a glossary page with a paragraph explanation? I would like to picture how the different terms can be listed.

Yes, I think that could be done.

"policy-server-cr": "[PolicyServer](https://blahblah)",

should be ok.

Also, we may want to think about TermWeb (I think you can get to it now, via Okta B2C), SUSEs new terminology database, as opposed to a in-house glossary.

viccuad commented 5 months ago

Also, we may want to think about TermWeb (I think you can get to it now, via Okta B2C), SUSEs new terminology database, as opposed to a in-house glossary.

I would prefer to link to a local glossary part of our docs. We are part of CNCF yaddayadda, plus ideally we should ship the docs somehow, in an airgap installation, without needing to hit external URLs.

jhkrug commented 5 months ago

Discussion

Considering, for the moment, just the term PolicyServer, capitalized in the Kubernetes style, it is a Kubewarden 'component'.

So, how should we be seeing PolicyServer in the documentation? It appears in both inline code-blocks and fenced code-blocks. When it appears in the text, in a sentence, is it always in an inline code-block? If not, should it be enclosed in either single or double quotation marks? Are we trying to indicate a difference between a PolicyServer in the text, and a PolicyServer in a code-block? I hope not, and I don't think we are.

So, if we want PolicyServer in the text to be both in an inline code-block for formatting/semantic reasons and we also want it to be a tooltip and a link to the glossary then the expansion of [[> policy-server-component <]] can be configured to look exactly like it currently does in an inline code-block, but colored a little differently to indicate it's a tooltip/glossary-link.

This is moving away from the semantic meaning of the markdown text which I'm reluctant to do.

Some clarification about our use of PolicyServer, and it's exact unquoted, quoted, code-block form in the text. Do we ever use 'PolicyServer', or PolicyServer, or is it always PolicyServer. Is this something we can make a decision on. It will probably simplify the options a little.

Options

Option 1

Use the pre-processor and the variable code to manage just a controlled vocabulary. So replace [[< policy-server-component >]] with PolicyServer. Purely plain text replacement by pre-processor before Docusaurus does anything else. It works cleanly and exactly as expected. This was the original idea.

Option 2

An idea from @viccuad, to have this variable construction insert a link to a glossary item. This would be quite nice. And rather than only a link, it could provide a tooltip, so navigation to the glossary entry and back again would not be necessary. This is not an extension of Option 1, but is different. The straightforward expansion does not work when inside code blocks, inline or fenced. So some sub-options need exploring:

Option 2a

Only use [[< policy-server-component >]] outside code blocks. Inside code blocks is verbatim code, obviously, so don't use a variable expansion. This works, it's simple again, and can be used to construct a tooltip and glossary link without issue. Unfortunately, it also moves away from the original idea of a controlled vocabulary, you still have to make sure you are using exactly the right terms inside code blocks, while using an expanding variable in the normal text.

Option 2b

Have [[< cb-policy-server-component >]] and [[< policy-server-component >]]. The first for use in a code block, the second for use in the normal text. The first expands to PolicyServer, the second adds in all the tooltip and link stuff.

Option 2c

This is introduced because from the reader's point of view it seems something might be missing if an inline code block PolicyServer does not have a tooltip and glossary link. Because as a reader you are just reading this in the flow of text. But, with styling, we can make [[< policy-server-component >]] expand to look exactly like an inline code block. But have a tooltip and a glossary link. Still need to have separate variables for if we want a different appearance 'PolicyServer' and PolicyServer. This one has semantic difference in the markdown now, we are no longer using an inline code block, when we mean an inline code block. Probably, not that important.

Any of the options may make migration to another docs toolchain more complex. Which currently does not appear to be an unlikely scenario.

viccuad commented 5 months ago

I vote 2a; codeblocks are self-explanatory. I would prefer to move forward without this overall feature than to complicate the docs.

jhkrug commented 4 months ago

Take a look at https://deploy-preview-396--silly-bunny-8cedd0.netlify.app/next/quick-start the first paragraph of bullet points for a better idea of how it might look.

Also please take a look at the glossary. Some terms are probably unnecessary there and some need to be added. If you want to contribute some pithy text for any of the entries, cool!

jvanz commented 4 months ago

I think the glossary is great! We are moving in the right direction. I'm not sure where we use all the terms, but I would say we can reduce the initial terms count there just for the ones more directed related to Kubewarden. Keeping only:

Or maybe keeping the term used in the Quick Start for now. I don't know... I'm just wondering about that.

jhkrug commented 4 months ago

Ready for review again. Keeping it in draft, I'm still not totally convinced. See what you think. The quick start page is the only one modified (so far) to use this idea of the controlled vocabulary.

jhkrug commented 4 months ago

LGTM

The glossary items and the position of the tooltips looks fine to me. I'm just not sure about the colors. But I do not know how to improve it.

Yes, it makes the page quite busy. I'm tempted to try no color in the text, so no visual indication at all that there is a tooltip. So, once you know there may be one, you can use it if you want to. It's not quite as invisible as it seems. It's surprising how much we use a mouse/pointer when reading.

jhkrug commented 4 months ago

Ok, I think this is the final version. Much more subtle.

jvanz commented 4 months ago

Ok, I think this is the final version. Much more subtle.

That's it! I like it

jhkrug commented 4 months ago

I think this can be merged. It could be improved further, by adding some code to reduce duplication in variables.json. For a future iteration, when docs infrastructure is decided on.