Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure the Concourse docs #136

Closed
clarafu opened this issue Dec 28, 2018 · 6 comments

Comments

@clarafu
Copy link
Contributor

@clarafu clarafu commented Dec 28, 2018

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.

@jama22

This comment has been minimized.

Copy link
Member

@jama22 jama22 commented Jan 21, 2019

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

@clarafu

This comment has been minimized.

Copy link
Contributor Author

@clarafu clarafu commented Jan 21, 2019

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
@topherbullock

This comment has been minimized.

Copy link
Member

@topherbullock topherbullock commented Jan 21, 2019

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.

@jama22

This comment has been minimized.

Copy link
Member

@jama22 jama22 commented Jan 22, 2019

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

@marco-m

This comment has been minimized.

Copy link
Contributor

@marco-m marco-m commented Jan 29, 2019

Is this related to #28 ?

@vito

This comment has been minimized.

Copy link
Member

@vito vito commented Feb 1, 2019

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

jama22 pushed a commit that referenced this issue Feb 13, 2019
@jama22 jama22 closed this Mar 6, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.