Thanks for providing more actionable feedback. Some follow-up questions / comments below:
why isn’t there an actual real-world example of the setup instructions?
The example command in step 4 is a real world command. Are you suggesting we use sample values instead of variable names? We use variable names by design because it prevents people from copy / pasting the command and using as-is.
We tried using sample values in the past and this ended up causing problems because so many people would copy / paste without replacing the sample values. This caused a lot of problems and created support burden.
This is the challenge with documentation. An approach that may benefit some users may cause confusion or be more error prone to other users.
If you have examples of (complex) systems that do a good job documenting installation commands, without being subject to the copy / paste issues described above, please post links so we can take a look and see if there is anything we can learn / borrow.
How are these placeholders related to the inputs to the Github OAuth form filled out in the previous step
The placeholders in the sample command are described in step 3. Do you have any suggestions for making this more clear?
In particular, I don’t see any documentation laying out the core concepts of how drone ci actually works; how it is integrated with Github OAuth exactly; again this sort of stuff is probably obvious to some people, but not to everyone.
Fair point.
Drone does not have its own login. Instead you Login with your GitHub account which is why you have to configure oauth2.
When I run the huge docker run command, I get a hash of some sort as output. What is this output? What did the command do actually?
The documentation should probably state that a working knowledge of Docker is a prerequisite to installing this software.
it is assumed the user already knows a few things, so the documentation is definitely not beginner friendly.
This is true and we should do a better job of documenting prerequisites.
For dev ops people, I think the succinctness of the documentation is probably well-received; but what about for people that don’t do this sort of thing all the time?
I agree.
It is important to remember that writing documentation that targets a wide audience requires a significant time investment and takes many iterations. When we write documentation the first draft may not appeal to a broad audience — this is because we are constrained by time and resources, because we may not know enough about our audience and their skill levels, and because we prefer to release early and gather feedback. Over time we collect feedback (like yours) and make improvements to appeal to a wider audience with varying backgrounds and experience levels.