Consolidate docs authoring, website, and maintainer info

[RichieEscarez]

What is changing?

Docs contributor docs were previously all in the knative/community repo, under the /docs folder (which had "docs owners" special access). Today, there are chunks of contributing, authoring, and website info across the /doc, /website/ and /community repos.

To make contributor and maintainer info accessible and discoverable, we should create a section in the website that functions as a consolidated single source for all this info (a new "/help" section in the site):

https://knative.dev/help/

How will this impact our users?

They will find what they are looking for and become fully independent docs contributors.

Design:

• Unlike the existing "Documentation" "Blog" and "Community" sections, the new "Help" section will not be exposed in the main website navigation.
• The /help/ section will have independent sections for:
  • "Help docs" - include page elements (ie. hugo, docsy, etc), required page and site frontmatter, blog info
    • New "how to contribute to docs" instructions #1917
  • "Maintaining docs" - how to: (1) update the API docs (2) create a new docs version/branch, (3) release and publish a version
    • Document the knative.dev maintainer instructions website#39
  • "Docs publishing" - how the site works, knative specific customizations, how to use hugo/docsy/netlify, regular maintenance tasks
    • [WIP] Docs release process #2668
• The content under the /help section will be strategically linked to from the main entry points for contributors
  • PR templates will include links to corresponding /help/how to do this topics
  • README.md, CONTRIBUTING.md, DEVELOPMENT.md, and others will link to the /help content (redirect all to this single source for all things docs)
• knative/community will continue to be the home for Knative member/contributor type info, AND crosslink between /help content

In what release will this take happen (to the best of your knowledge)?

v.next

Context

• https://knative.dev/community/contributing/docs/docs-contributing/ (https://github.com/knative/community/tree/master/docs)
• https://github.com/knative/docs/blob/master/README.md
• https://github.com/knative/docs/blob/master/CONTRIBUTING.md
• https://github.com/knative/docs/blob/master/new-page-template.md
• https://github.com/knative/website/blob/master/DEVELOPMENT.md
• https://github.com/knative/website/blob/master/scripts/build.sh
• https://github.com/knative/website/blob/master/scripts/localbuild.sh
• https://github.com/knative/docs/tree/master/blog

TODOs

• (Consolidate all "docs" help info into single location #3437) Move all information into a /help folder in the knative/docs repo
  (URL: https://github.com/knative/docs/tree/main/help)

  • (Consolidate all "docs" help info into single location #3437) knative/docs repo
  • ()Move docs contrib to help section community#557 knative/community repo
  • Make sure "repo only" files are excluded from the Site build (ex. https://knative.dev/contributing/)

• Add/replace existing README.md, CONTRIBUTING.md, and DEVELOPMENT.md content with links to these new "docs contributor how-to guidelines"

  • (Consolidate all "docs" help info into single location #3437) knative/docs repo
  • (Move docs contrib to help section community#557) knative/community repo

• (Consolidate all "docs" help info into single location #3437) Consolidate and fix "docs" and "blog" GitHub templates for PRs New blog template and update doc template #3341

  • (Enable new "help" section and fix a few things website#288) Add links within the templates to point to these new "docs contributor how-to guidelines" Add links to new content templates community#531

• (Enable new "help" section and fix a few things website#288) knative/website repo

  • Add new help section to the knative.dev site/build
  • Add "Help" links next to GitHub links in the right-hand side bar
    

• Instructions for website:

  • (Consolidate all "docs" help info into single location #3437 - incomplete draft) publishing
  • (Consolidate all "docs" help info into single location #3437 - incomplete draft) maintenance
  • (Consolidate all "docs" help info into single location #3437 - incomplete draft) docs release process

[RichieEscarez]

Current state (running locally):

[abrennan89]

Thanks for taking on the blog stuff with all of this @RichieEscarez !
Do you think we could set some preliminary dates / milestones for completing aspects of this work? Is it long term stuff that should be added to the roadmap for this year?