GitHub Docs: love it or hate it? We want to hear from you!

[felicitymay]

What: We want to hear about your experiences using technical documentation.

Why: To help us improve the documentation experience for GitHub users, we want to understand how, when, and why users reference technical documentation, including GitHub Docs.

How: Add a new comment to this discussion describing the last time you used technical documentation to complete a task, including:

1. What was your task?
2. What information did you need?
3. How did you look for the information?
4. Were you successful in finding the information you needed? How did you know when you'd done so? 
5. If you can, share a link to the information you used. Or, if there's any documentation you specifically loved or hated, we'd love to have you point us to it. 

Many thanks for helping us learn more about our users 🙇

[llvee]

@felicitymay

Thank you for taking the time to open this discusssion.

1. What was your task? Reviewing repository security
2. What information did you need? Repository invitation content
3. How did you look for the information? Searching Docs, Relevant Docs Pages
4. Were you successful in finding the information you needed? How did you know when you'd done so? No because the relevant pages lacked specific information needed to ascertain security implications of inviting collaborators to repositories 
5. If you can, share a link to the information you used. Or, if there's any documentation you specifically loved or hated, we'd love to have you point us to it. 

I recently opened some similar discussions around improving skills, docs especially the above as I realised it's quite important since GH has so many users.

Do you mind if I share/link relevant issues, discussions here?

Are you interested in exploring unifying efforts more on improving GH with other engineers like myself that don't presently work directly for GH?

Today while browsing docs repositories, I did find myself questioning why the docs themselves aren't in code repositories on GH for easier editing.

Are you able to shed any light on that?

[felicitymay]

Hi @llvee - thanks for your message ✨

Do you mind if I share/link relevant issues, discussions here?

I'm happy for you to link relevant issues or discussions here.

Today while browsing docs repositories, I did find myself questioning why the docs themselves aren't in code repositories on GH for easier editing.

The source files for GitHub's user documentation are stored in the public repository: https://github.com/github/docs and we encourage contributions from open source contributors. For more information, see the README file.

[ClemRelativity]

1. What was your task?
   We developed a set of reusable workflows, one of which required CLI authentication. We wanted to use federated credentials on github environments and an external secret store where our Service Principals' credential was stored and managed (rotated). This would allow us to fetch the secret for the SP without having to do any hard coding of secrets.

So we needed to add this credential fetching using the federated credential environment. We also wanted to have approval steps on those environments.

2. What information did you need?

How to matrix based reusable workflows interact with environments with approval steps? For example, if I do a matrix strategy, do I have to approve each job in that matrix that uses that environment? We only wanted one approval step for all items in that matrix.

How to pass secrets from workflow to workflow.

4. How did you look for the information?

Diving into the documentation! This was my entry point: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions and I really liked branching off of this.

6. Were you successful in finding the information you needed? How did you know when you'd done so?

Not so much. I felt that matrix documentation could have more information on what I wanted regarding how these jobs get created and how they interact with environment approval steps. The information regarding secrets from workflow to workflow was good!

[felicitymay]

Thank you for sharing your experience. It's really interesting to see examples of different use cases, how people approach them, and where they look for information in the docs to support their work 💖

[neongreen]

1. What was your task?

I wrote a workflow to publish documentation previews for PRs, and wanted to figure out the security properties of the workflow.

2. What information did you need?

The precise semantics of GitHub Actions:

• Which exact version of the workflow file will be used?
• Which information is considered when triggering a workflow? (eg. does the definition in the default branch affect anything re/ execution of workflows in other branches?)
• Are jobs isolated from each other? How are reusable workflows executed?
• How are caches scoped?

3. How did you look for the information?

At first I was looking through GitHub Docs, then I gave up and started reading security conference papers and various gists.

4. Were you successful in finding the information you needed? How did you know when you'd done so?

I still don't know if I have an accurate understanding of GHA. I filed github/docs#35318 and github/docs#35317.

5. If you can, share a link to the information you used. Or, if there's any documentation you specifically loved or hated, we'd love to have you point us to it.

https://github.com/0xn3va/cheat-sheets/blob/main/CI%20CD/Github/actions.md, https://www.usenix.org/system/files/sec22-koishybayev.pdf, https://github.com/nikitastupin/pwnhub/blob/main/writings/pwn-request-via-non-default-branch.md were helpful.

I didn't manage to get a good understanding of GHA semantics from the GH docs at all. The pages link to each other a lot, and the crucial information is scattered across many different pages.

For example — I read through Events that trigger workflows many times. It never actually explains which version of the workflow file is used. This is explained in Triggering a workflow, but I never looked at "Triggering a workflow" because I assumed it was a beginner guide and "Events that trigger workflows" was the complete reference. "Events that trigger workflows" lists GITHUB_REF and GITHUB_SHA for each event, but doesn't explain what they mean.

For events like create, I still have no idea if my interpretation is correct. It seems like with create it's impossible to have a default-branch workflow that would receive information about all create events in the repo, which is rather counter-intuitive.

For nested workflows, I still don't know if they are guaranteed to run in a different VM (when using GHA runners) or not. I assume they are.

For caches — I have no idea for the cache security model. My current understanding is that when pushing into cache, ACTIONS_RUNTIME_TOKEN is scoped to the GITHUB_REF of the workflow run. But is it actually GITHUB_REF, or not quite? What is the scope for workflow runs where GITHUB_REF is a simulated merge of base+PR? What is the scope for on: pull_request runs for merged PRs (where GITHUB_REF is /refs/heads/main)? Is the extra / at the beginning relevant?

Overall, my impression of the docs is that they give a lot of advice, like "You can do X to achieve Y", or "Use [trigger] in [some circumstances]", but don't give a reference for GHA behavior/semantics.

[felicitymay]

Thank you for taking the time to respond to our request in such detail. It is really helpful to hear about user journeys through the documentation and what's missing.

Thank you also for filing issues in the Docs repo for specific problems that you identified. ✨