Restructure the Concourse docs

[Clara Fu]

The way that our docs are currently structured, it can be hard for some of our users to use. It is not very straightforward or easy to find where certain docs are. One example of a suggestion, all the actual docs or the place that many people would go straight to is in the "Reference" section, but it might be confusing since "Reference" sections can mean citations in webpages. Another suggestion was to bring back the one-page docs in order for faster lookup through CTRL-F.

These two points are just a couple of places that we can start at for restructuring and improving our docs. Currently, our docs is one of the main pain points of many of our users and we should try to make it as easy and extensive as possible.

This will probably be a long running issue, I'm just opening this to keep track of ideas and work that I will do to improve our docs.

[James Ma]

I agree that we can do a bit of restructuring. A lot of the current layout was influenced by how other OSS projects structure their docs. For example, the k8s documentation site:

https://kubernetes.io/docs/home/?path=users&persona=app-developer&level=foundational

Uses the following L2 Nav labels:

• Setup
• Concepts:
• Tasks
• Tutorials
• Reference
• Contribute

Our docs, as of Jan 21 have:

• About
• Setup & Operations
• Concepts
• Tutorials
• Reference
• Contribute
• Community
• Trademarks

I'm not sure what the new layout should be, but maybe a restructuring and separation?

• About
• Setup -> more lightweight and specific docs on how to get up and running with various forms of Concourse
• Reference
  • Operations
  • Current reference docs (*5.1 - 5.7)
  • web node docs?
• Concepts Concourse Internals
• Tutorials & Tools
• Contribute
• Community
• Trademark

cc @vito @Lindsayauchin @topherbullock

[Clara Fu]

Maybe instead of all these categories being under the header of "Docs", we can split it out to

• About
• Setup -> more lightweight and specific docs on how to get up and running with various forms of Concourse
• Documentation
  • Concepts Concourse Internals
  • Tutorials & Tools
  • Operations?
  • Current reference docs (*5.1 - 5.7)?
  • Web node docs?
• Contribute
• Community
• Trademark

[Topher Bullock]

I like the idea of categorizing Documentation under sub-types, but keeping Setup / Getting Started guides at the top level.

I think Reference could include Operations, and more of a laundry list of configuration options available for web + worker.

[James Ma]

Oh and an "Example" section for @osis hard work in the example branch

[Marco Molteni]

Is this related to #28 ?

[Alex Suraci]

@marco-m Not really, that issue can just be garbage collected. That issue is pretty old and predates the existing structure.