Phase 1: Adding documentation metadata tags

[evankanderson]

Proposed Changes

In preparation for a CNCF TechDocs Assessment, start labelling Knative documentation with metadata to assist with re-organizing content to different information architecture options (we will still need manual review, but this may simplify that review).

I'm using a schema with 3 fields:

field	allowed values	explanation
audience	developer, administrator, buyer, contributor	Who the target audience is; ensure documents have a clear, single audience
components	eventing, functions, serving (list)	What components are featured on the page.
function	marketing, community, tutorial, how-to, reference, explanation	A diataxis tag or "marketing" or "community" indicating the needs addressed by the documentation.

[netlify]

✅ Deploy Preview for knative ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	aaac40e
🔍 Latest deploy log	https://app.netlify.com/projects/knative/deploys/6870c38a70f3ee00087d806b
😎 Deploy Preview	https://deploy-preview-6274--knative.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[knative-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: evankanderson

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [evankanderson]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[evankanderson]

https://diataxis.fr/complex-hierarchies/#two-dimensional-problems may be helpful when figuring out how to structure these eventually.

[evankanderson]

@dwelsch-esi -- PTAL (please take a look), as this should help (hopefully) with the initial phase of techdocs assessment. If this makes sense to you, then you can reply with /lgtm at the start of a line, and Prow will merge this PR (and it will be pushed to Netlify / go live). You can also take a look at the Netlify preview, though it should be roughly identical to the current live site, as the new metadata is only in the source code.

[dwelsch-esi]

@evankanderson, Just one minor question regarding audience:

The same page can be relevant to more than one audience. Looks like you've inserted comments to that effect in some of the files, for example docs/eventing/accessing-traces.md:

audience: administrator
# And audience: developer for accessing traces

Is there a reason you didn't make this field a list like you did for components? Regardless, I don't think this is a big deal -- I'm sure the role you've identified in each case is the primary audience for the page. If the meta tags become super important later, you could open another PR to update them, but I don't think this question is worth holding up the merge.

/lgtm

[knative-prow]

@dwelsch-esi: changing LGTM is restricted to collaborators

In response to this:

@evankanderson, Just one minor question regarding audience:

The same page can be relevant to more than one audience. Looks like you've inserted comments to that effect in some of the files, for example docs/eventing/accessing-traces.md:

audience: administrator
# And audience: developer for accessing traces

Is there a reason you didn't make this field a list like you did for components? Regardless, I don't think this is a big deal -- I'm sure the role you've identified in each case is the primary audience for the page. If the meta tags become super important later, you could open another PR to update them, but I don't think this question is worth holding up the merge.

/lgtm

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[evankanderson]

@evankanderson, Just one minor question regarding audience:

The same page can be relevant to more than one audience. Looks like you've inserted comments to that effect in some of the files, for example docs/eventing/accessing-traces.md:

audience: administrator
# And audience: developer for accessing traces

Is there a reason you didn't make this field a list like you did for components? Regardless, I don't think this is a big deal -- I'm sure the role you've identified in each case is the primary audience for the page. If the meta tags become super important later, you could open another PR to update them, but I don't think this question is worth holding up the merge.

Generally, I'm suspicious of trying to target more than one audience or purpose in a single document. In cataloguing our current docs, we do mix these audiences, but I would probably prefer to move a bunch of the installation docs separate from the usage docs, rather than encourage this mixing.