taylorsilva
commented
2 years ago This is fantastic! I've been writing/updating most of the docs and I'm not a docs writer, so it's been hard for me to see where to further take the docs to make them better. This is exactly what we need.
I like the proposed breakdown between the types of users and the docs meant for each group. I think it would be a huge improvement over the current structure.
I've got a lot going on right now, so definitely don't have time to work on this in the short-term, but happy to shepherd any PR's you start.
tomschr
Situation
I really like Concourse and its features. :heart: Also the documentation gave me a good insight into the possibilities.
However, I see some issues with the current documentation:
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:
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:
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:
IMHO, the structure takes into account the different level of knowledge about Concourse.
What do you think?