Docs Reorg for v1.11

[plumbis]

This is a rework of PR #254.

Summary of changes

• The creation of a "Knowledge Base" for content that is not version specific and can be more in depth on a single topic or cross multiple topics.

• The creation of a "Developer Guide" covering contributing to the Crossplane docs and a pointer to the crossplane/crossplane CONTRIBUTING.md

• A significant reorganization of files within a docs version. This reorg is currently only for the master branch docs and will be applied to version v1.11 and new versions going forward. Existing version pages will not be changed (read: no broken bookmarks)

Changes from #254

• All information about contributing to Crossplane source was removed at the request of @negz.
  Ref: [Do not merge] Proposed Docs Reorg #254 (comment)

• Many additional file changes were pushed into smaller PRs that are already merged including:

  • Create a home landing page and styling to stage for v1.11 reorg #268
  • Rework sidebar. Simplify code and enable for support for KB and contrib #267
  • Make navbar Documentation Link relative to environment #266
  • move content media to top level folder #265
  • Alert when a feature is alpha/beta #263
  • Combine list and single page layouts into a single file #262
  • Moves the search box JS from end of page to search div #259

Work in progress

A few things are still required to have MVP content for v1.11's release:

• Install/Uninstall/Upgrade chapters need to be written
• Quickstart guides need to be reviewed extended to include XRs and Claims

[netlify]

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	80d9a42
🔍 Latest deploy log	https://app.netlify.com/sites/crossplane/deploys/63d994bc1ee0b70008a38ba4
😎 Deploy Preview	https://deploy-preview-271--crossplane.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 site settings.

[burnyd]

LGTM! Nice examples and explanations.

[jeanduplessis]

@plumbis this PR, #267, still needs to be merged but mentioned in the description that it should already be merged.

[jeanduplessis]

@plumbis I'm struggling to make sense of the new information architecture with regards to Documentation, Contributing Guide and Knowledge Base.

For instance if I'm on the Documentation overview, I don't see any way of accessing the Contribution Guide or Knowledge Base?

And if I'm on the Knowledge Base I don't see how it fits into the overall Documentation, since the left nav is totally different. Same for Contributing Guide.

What are the expected user journeys that get you to the new Knowledge Base and Contributing Guide sections and how does it relate to the overall Documentation section?

[jeanduplessis]

It would be good if we can fix the spacing for the items below the "On this page" right hand menu.

[plumbis]

@jeanduplessis just pushed a fix for the spacing between github buttons with e67e63c

[jbw976]

@jeanduplessis just pushed a fix for the spacing between github buttons with e67e63c

I still see a lack of spacing when looking just now at the deployment preview and doing a hard refresh, e.g. https://deploy-preview-271--crossplane.netlify.app/v1.11/. I wouldn't block the PR on it, but curious why it doesn't appear fixed for me.

[plumbis]

@jeanduplessis just pushed a fix for the spacing between github buttons with e67e63c

I still see a lack of spacing when looking just now at the deployment preview and doing a hard refresh, e.g. https://deploy-preview-271--crossplane.netlify.app/v1.11/. I wouldn't block the PR on it, but curious why it doesn't appear fixed for me.

That was originally for vertical spacing and I didn't notice the horizontal spacing. Just pushed a fix.

[jbw976]

@plumbis in general, the new docs site and content is looking fantastic!! 🔥

there may be some parts of the details and flow that we want to tweak after running through them more completely in the near future, but overall I don't see major show stoppers in this new docs experience that would prevent us from shipping today. we can make tweaks as they come up via feedback in the near future.

i'm still a bit confused (and potentially concerned) about how the maintenance and backporting of updates to the docs content will work, but I think that's also out of scope for this PR and that decision was already made when moving the docs out of the c/c repo. Perhaps pointing me to the process/instructions for backporting will be helpful.

Thank you again for this massive effort and making the crossplane docs better @plumbis!! 💪

[plumbis]

@jbw976

i'm still a bit confused (and potentially concerned) about how the maintenance and backporting of updates to the docs content will work, but I think that's also out of scope for this PR and that decision was already made when moving the docs out of the c/c repo. Perhaps pointing me to the process/instructions for backporting will be helpful.

All of the docs across every version lives inside the /content directory. To backport a fix you just edit the same file in the other directory. For example, fixing a problem in /getting-started/_index.md would mean the same fix is applied to /content/v1.11/master/getting-started/_index.md and /content/master/getting-started/_index.md.

This is mentioned briefly in the new contributors guide
https://deploy-preview-271--crossplane.netlify.app/contribute/contribute/#contribute-to-a-specific-version

(this link won't work until this is PR is merged)
https://docs.crossplane.io/contribute/contribute/#contribute-to-a-specific-version

[negz]

Just to be explicit - feel free to proceed without my approval. I haven't had time to review this deeply. I feel okay about following up with any changes post release.

[negz]

I will note though I'm currently seeing "User Documentation" written twice.

[plumbis]

"User Documentation User Documentation" was because master had the wrong version number. Fixed.

[jbw976]

Note that DCO was manually approved because of https://github.com/crossplane/docs/pull/271/checks?check_run_id=10851743149

There's a discrepancy in @plumbis sign-off for a commit from Github. However, the intent of the DCO is met: pete@upbound.io signed-off for plumbis@users.noreply.github.com. It would be nice to update the commit metadata to make it perfectly matching, but that proved difficult to update because there are merge commits after that commit that had conflicts.

We are moving forward with a manual DCO approval because the DCO intent is met.