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. ✨

[thecatfix]

Giddy up Github Page Adventure

What was your task?

Setup Github Pages For Personal and Organization

What information did you need?

I was so ecited to setup the page b/c I thought it would be so simple. I was wrong and I should have been smarter.
Precise instructions on how to setup a page for personal and organization

How did you look for the information?

Searched on Github pages and then spent about 10 days trying to understand all of the settings.

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

Nope. I gave up trying to figure out Jekyll and Gatsby

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 created a bundle of articles just b/c you asked.
GitHub Pages URLs
Here is the repository. I unarchived for this feedback.
The Github Page Repository

[felicitymay]

I'm sorry to hear that you had such a very frustrating experience 😞

Many thanks for taking the time to leave this feedback so that we can learn from it 💖

[thecatfix]

I'm sorry to hear that you had such a very frustrating experience 😞

Many thanks for taking the time to leave this feedback so that we can learn from it 💖

Don't be sorry at all. I am learning as I go and I think I am finally starting to understand the power of version control and git. I really appreciate the effort collecting feedback.

[adlai]

My complaint in some Issue that seemed to invite conversation caused excessively harsh moderation actions following Report_Content.Choose_a_Reason->Spam on the comment; I don't care if it was automated or human-approved, the lack of response to my ticket requesting reinstatement is frankly insulting and reduces my will to use your website, regardless of the quality and clarity of technical writing in any of your documentation.

My only consolation is that after the moderation action, the Issue was locked, rather than leaving it open to further the illusion of an audience welcoming similar complaints.

In the interest of compliance with your natural-language contract...

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?

Improving my will to engage with the social network surrounding the webpages of repositories served by your infrastructure, by restoring my faith in the good standing of my only registered account.

2. What information did you need?

Several unspecified walkthroughs of moderation policies and recovery steps; due to the pervasive culture of making unsolicited conversation as difficult as possible, Industry Best Practice is to obfuscate and obscure these policies, if they are even published... otherwise, it becomes incredibly easy to social-engineer your way into above-mean standing without actually being a contributing member of any community.

3. How did you look for the information?

Terribly, and only effectively after taking a break, saving my progress notes outside of the website in case my access got further disabled by angry moderator actions, and then resuming from where I had stopped. I will not share my browser history.

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

No, because the ticket requesting any response whatsoever to my appeal has not received any response, whatsoever!

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

• Similar complaint GitHub Docs: love it or hate it? We want to hear from you! github/docs#34730 (comment)
• Official Moderation Policy Disclosure https://docs.github.com/en/site-policy/acceptable-use-policies/github-appeal-and-reinstatement
• DONTCLICK // HONEYPOT? // 301 !!!

[felicitymay]

Hi @adlai

I'm sorry to hear that you had a bad experience in the docs repository. I'm not part of the moderation team for the repository.

I suspect that your comment was hidden because we're unable to update the site policy articles directly in this repository. They are maintained in https://github.com/github/site-policy. Once changes to site policies are agreed and reviewed by our legal team, the updates are transferred across to the docs repository.

[adlai]

I'm sorry to hear that you had a bad experience in the docs repository. I'm not part of the moderation team for the repository.

ok @felicitymay that is completely understandable when interacting with companies as complicated as Microsoft subsidiaries!

I suspect that your comment was hidden because we're unable to update the site policy articles directly in this repository. They are maintained in https://github.com/github/site-policy. Once changes to site policies are agreed and reviewed by our legal team, the updates are transferred across to the docs repository.

Thank you, that is incredibly relevant information, and actionable! I'll queue some follow-up conversation with employees after I've surveyed the /github/** routes and the docs subdomain a little more thoroughly, to reduce the likelihood of incurring silent moderation wrath with the next notification.

[rizkyy702]

love it

[wolfy1339]

1. What was your task?
   Mocking webhooks in tests
2. What information did you need?
   Example payloads for Webhooks event
3. How did you look for the information?
   On the GitHub docs website
4. Were you successful in finding the information you needed? How did you know when you'd done so?
   No.
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.

Missing payload examples for Webhook events is one of my major issues with the docs,
github/rest-api-description#4552
github/docs#22726

This issue was raised initially over 2 years ago, and there has been no visible resolution or update since the initial contact.
While the previous iteration of the webhooks docs were not perfect, they had a valuable asset: examples!

We collected many payload examples over in octokit/webhooks, but they are frequently out of date and only based on user gathered data.

[felicitymay]

Thank you. I'll take a look to see if can find the appropriate place to bump this request.