feat: add administration and installation docs

[jbrockopp]

closes go-vela/community#4
closes #250

This adds administration and installation documentation for Vela.

Here are some of the sites used for inspiration with this content:

• https://circleci.com/docs/2.0/server-3-overview/
• https://concourse-ci.org/install.html
• https://docs.drone.io/runner/overview/
• https://docs.drone.io/server/overview/
• https://docs.github.com/en/actions/
• https://docs.gocd.org/current/installation/
• https://docs.travis-ci.com/user/enterprise/
• https://www.jenkins.io/doc/book/installing/

There is a lot of new pages and lines of code added with this change.

Due to this, I've created a fork to improve the experience when reviewing the content:

https://jbrockopp.github.io/docs/administration/

A quick link to the documentation for each service:

• https://jbrockopp.github.io/docs/administration/server/
• https://jbrockopp.github.io/docs/administration/worker/
• https://jbrockopp.github.io/docs/administration/ui/

[JordanSussman]

initial feedback

[jbrockopp]

@jonathonlacher thanks for reviewing and appreciate the feedback 🎉

For context, here are some of the sites being used for inspiration with this content:

• https://circleci.com/docs/2.0/server-3-overview/
• https://concourse-ci.org/install.html
• https://docs.drone.io/runner/overview/
• https://docs.drone.io/server/overview/
• https://docs.github.com/en/actions/
• https://docs.gocd.org/current/installation/
• https://docs.travis-ci.com/user/enterprise/
• https://www.jenkins.io/doc/book/installing/

but my main feedback is that I think there needs to be greater differentiation between the different types of documentation. For background, a while ago I found this explanation of the 4 types of documentation: tutorials, how-to guides, reference, and explanation.

Thanks for the link! Do you by chance have a doc site you are aware of that embodies this approach?

I ask because I would like to see a real-world example of this approach in action as I'm struggling to understand it.

To be more specific, most tutorials I've seen on doc sites contain content relating to the tutorial with the how-to-guide embedded in the tutorial. I would be confused for a tutorial to skip providing the tasks required to complete the learning.

Also, the tutorials I've had the greatest experiences with provide explanative information along the way to augment the experience and enhance the learning as you're going through the steps to complete the tutorial.

I find it very difficult to drive the differentiation between a tutorial and a how-to guide so hoping an example would help.

Here are some examples to help illustrate what I mean where it seems the tutorial and how-to-guide are synonymous:

• https://docs.docker.com/get-started/
• https://kubernetes.io/docs/tutorials/

You do have an explicit reference section of the docsite, and then under the Administration section, the server, worker, and UI each have their own reference section.

Ok so thinking how to digest this feedback and take action.. would it be better to move the reference docs for each service under administration to the global reference section?

Also the Administrative section in total a mixture of explanation, reference, and how-to. I haven't given much thought to alternative documentation layouts, but as someone less familiar with the inner workings of Vela it's not intuitively obvious which documentation section will have the info I'm looking for.

Do you think it would help if we added more information to the administrative and reference sections?

Maybe adding details that help distinguish what content can be found in these sections?

[cognifloyd]

For the env var docs, it would be nice to make required vs optional much more apparent at a glance.

Plus a variety of other comments.

[jbrockopp]

For the env var docs, it would be nice to make required vs optional much more apparent at a glance.

Plus a variety of other comments.

@cognifloyd thanks for reviewing and appreciate the feedback 🎉

thoughts on how to accomplish this (required vs optional)?

Would making this bold for each variable be enough?

[cognifloyd]

thoughts on how to accomplish this (required vs optional)?
Would making this bold for each variable be enough?

Yeah, I think bold should be enough. Maybe a future version can adjust the formatting even more, but bold should be good enough for now.

[wass3r]

but my main feedback is that I think there needs to be greater differentiation between the different types of documentation. For background, a while ago I found this explanation of the 4 types of documentation: tutorials, how-to guides, reference, and explanation.

Thanks for the link! Do you by chance have a doc site you are aware of that embodies this approach?

i have brought up this document before as well. The site has a "Who's using this?" section here: https://documentation.divio.com/adoption/

it might make sense to open a new issue for that - it does feel a bit beyond the scope of this PR as it may affect the whole doc site?

it would also be nice to add an explicit self-contained tutorial for setting up the whole system.

potentially, this might be are more direct action item. @jonathonlacher, what approach did you envision here though? aws, heroku, gcp, etc? or just locally? docker compose? or something else?

[JordanSussman]

May take a little while to complete the outstanding feedback since @jbrockopp is on vacation until next week.

[jbrockopp]

but my main feedback is that I think there needs to be greater differentiation between the different types of documentation. For background, a while ago I found this explanation of the 4 types of documentation: tutorials, how-to guides, reference, and explanation.

Thanks for the link! Do you by chance have a doc site you are aware of that embodies this approach?

i have brought up this document before as well. The site has a "Who's using this?" section here: https://documentation.divio.com/adoption/

it might make sense to open a new issue for that - it does feel a bit beyond the scope of this PR as it may affect the whole doc site?

Agreed 😅

It sounds like we should open one or more issues to try and address reformatting for the entire site

[cognifloyd]

Good enough for a docs MVP.

[jbrockopp]

@cognifloyd FYI - made some changes based off internal feedback on the reference pages with all the variables

[cognifloyd]

That's much nicer!

[KellyMerrick]

lgtm