Consider a better separation between different users and tasks, concepts, and references? #482
Comments
|
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. |
|
Thank you for your kind word, Taylor. I hope my text wasn't too mean or discouraged you. Tried to be quite the opposite! I would really like to see the documentation as a proud testament of all the possible things that can be done with Concourse. I'm happy if my proposal makes sense to you. Even if it is still a little half-baked. 😉 The reason for this issue is, I'm a beginner. Perhaps I'm a good candidate for all the traps and mistakes you can make. 😆 The Getting Started served me quite well, but then I got confused where to go and felt a bit lost. Maybe it was just me. I can try to kickstart the process a bit. However, when I try to build the documentation with |
It had quite the opposite effect! It was all quality, constructive feedback. It made me feel energized and excited about the docs! 😃
Maybe try running |
Haha, that's great! 👍 😄
I've tried that, see the log below. I run it on openSUSE Leap 15.2. I also added the log from the Not sure what I did wrong. Used the instructions from the README. Log from "go mod download" (click me)Log from ./scripts/build -s 8000 (click me) |
|
That's weird that you're getting stuff like I'm on a new machine right now and I don't get any errors from I'm also having trouble building on this new machine that hasn't built the docs before. ./scripts/buildNot sure what that's about 🤔 EDIT: nvm, found out it's due to a rogue slash and probably the latest version of booklit changing a bit too |
|
It's building fine for me now on a new machine (macos) with go 1.17.2 |
|
Thanks for all the tips, updating to go1.17 and adding I forked the repo already, will create a branch, and try to work a bit on the idea. I don't know where it leads us. When I will have something to show, I'll come back and will notify you. |
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:
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?
The text was updated successfully, but these errors were encountered: