Consider a better separation between different users and tasks, concepts, and references? #482
Description
Situation
I really like Concourse and its features. ❤️ Also the documentation gave me a good insight into the possibilities.
However, I see some issues with the current documentation:
- "Docs" as a title isn't a particular good title (although I understand you need to separate it from other content)
- There seems to be no clear distinction between different users or target groups. For example, a total beginner needs different documents than a more advanced user or even an admin. Although the "Getting started" addresses the beginner, it's not clear what comes next. The admin isn't really mentioned at all.
- Structure-wise, the doc doesn't distinguish clearly between tasks, concepts, and references (see below about this idea).
- Some examples are quite advanced, for example the section Test, Build & Deploy. Unfortunately, this example uses Terraform which is a bit unfortunate. Although you don't have to completely understand Terraform to use it, it raises the bar quite high and creates an unnecessary dependency. As test, build, and deploy is quite a common approach, there should be a simpler example which doesn't depend on Terraform.
The overall goal is to make the documentation even more useful, accessible, and easier to understand.
Suggestion
I understand that the above points are maybe a bit too much for this single issue. Probably we can split it up into different, independent issues that drives to a common goal. For example, the example could be solved independent from this overall idea.
Not sure if you know already, but one way to organize documentation would be into tasks, concepts, and references. That idea comes from topic oriented writing:
- Task: the "recipes" where the real work takes place. Things the user needs to do. Usually organized in procedures with several steps. Examples are "Getting started with Concourse", "Starting a pipline" etc.
- Concept: informs the user about background information in a greater context. They are neither tasks nor references. For example, "Inputs and Outputs", "Auth & Teams" etc.
- References: shows details about CLI, API, pipeline format etc. It's more of a dictionary-type document. You only read it if you need a keyword, a structure etc. Examples are " Pipeline schema format", "API reference" etc.
That sounds like a huge task and probably it can be depending on how much effort you put into it. We already have a lot of good sections, I think a good start is to have some clearer structure and better titles. If we want to follow this approach, we could try the following steps:
- Go through each topic and sort it into a task, concept or reference.
- Set for each topic where it is targeted to: beginner, advanced user, or admin.
- Rephrase the title according to its type. If it's a task, start with a verb ("Starting a pipeline"). If it's not a task, start with a noun.
- If topics are missing, open an issue or write them.
- Regroup the sections so it makes sense.
So here is a short idea for a different structure. I don't say, it's perfect and it probably isn't. It should only serve as an inspiration. There are plenty of other ways to do it, there is no right or wrong:
For Beginners
* Getting Started with Concourse (<= absolute beginner would start here)
* Using the fly CLI command
* What's next?
For advanced users
* Installing Concourse
* Using GitHub repos in pipelines
* Running a pipeline in CLI and GUI
* Inputs and outputs
* Resources
* Introduction to YAML
* Common Pipeline practices
For admins
* Maintaining Concourse server
* Creating teams
* Passing parameters to API calls
* Knowing authentification
* [...]
References
* Pipeline schema format
* API
* Internals
* [...]
IMHO, the structure takes into account the different level of knowledge about Concourse.
What do you think?