Docs: 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 "/authoring" section in the site):

https://knative.dev/authoring/

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 "Authoring" section will not be exposed in the main website navigation.
• The /authoring/ section will have independent sections for:
  
  
  
  • "Authoring docs" - include page elements (ie. hugo, docsy, etc), required page and site frontmatter, blog info
    
    
    
    
    
    • https://github.com/knative/docs/issues/1917
    
    
    
  
  
  • "Maintaining docs" - how to: (1) update the API docs (2) create a new docs version/branch, (3) release and publish a version
    
    
    
    
    
    • https://github.com/knative/website/issues/39
    
    
    
  
  
  • "Docs publishing" - how the site works, knative specific customizations, how to use hugo/docsy/netlify, regular maintenance tasks
    
    
    
    
    
    • https://github.com/knative/docs/issues/2668
    
    
    
  
  
• The content under the /authoring section will be strategically linked to from the main entry points for contributors
  
  
  
  • PR templates will include links to corresponding /authoring/how to do this topics
  
  
  • README.md, CONTRIBUTING.md, DEVELOPMENT.md, and others will link to the /authoring 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 /authoring 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

• [ ] Move all information into a /authoring folder in the knative/docs repo
  (URL: https://github.com/knative/docs/tree/master/authoring)

  • [ ] knative/docs repo
  • [ ] 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"

  • [ ] knative/docs repo
  • [ ] knative/community repo

• [x] Consolidate and fix "docs" and "blog" GitHub templates for PRs https://github.com/knative/docs/pull/3341

  • [x] Add links within the templates to point to these new "docs contributor how-to guidelines" https://github.com/knative/community/pull/531

• [ ] knative/website repo

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

[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?

[omerbensaadon]

@RichieEscarez moved this to backlog since looks like you're currently working on it.

It's also in the [EPIC] Clean Up the Cruft as "in progress"

Keep me posted if you want me to split out some of this stuff as separate issues?

[RichieEscarez]

Made a little progress on this:

[omerbensaadon]

@RichieEscarez I would push that with some //TODOs, doesn't have to be perfect 👍🏼

PS: If you want to work on it solo I would still push and just put //TODO @RichieEscarez

[RichieEscarez]

@RichieEscarez I would push that with some //TODOs, doesn't have to be perfect 👍🏼

PS: If you want to work on it solo I would still push and just put //TODO @RichieEscarez

Yes, thats the plan. Thanks Omer! I almost got it to a state to push but I ran out of time (lots of distractions lately from various request combined with lots of merge conflicts and changes within the files im touching). Generally there are updates across knative/docs, knative/website, and knative/community (since duplicate and outdated info exists throughout), so theres a lot of coordination, testing, and rebasing to be able to consolidate this stuff.

[omerbensaadon]

@RichieEscarez ok awesome!

@snneji @RichardJJG could be good folks to review this since they are fairly new 🥇

[RichieEscarez]

Version sent for review (a lot of the "website" section have Todo's):