Improve GitHub Developer Program README for clarity and structure

[AzizB283]

Code of Conduct

• [x] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

Hi team

I'd like to suggest an improvement to the github/docs GitHub Developer Program page. After reading the current version, I noticed several opportunities to improve clarity, usability, and structure for both new and returning developers.

What part(s) of the article would you like to see updated?

Lack of clarity and purpose

• The introduction is brief and doesn’t clearly explain what the Developer Program is, who it is for, or what benefits it offers.

No TL;DR or structured overview

• There's no quick summary or organized layout that guides the reader.

• Readers must scroll and interpret scattered information on their own.

Additional information

No response

[welcome[bot]]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[Sharra-writes]

@AzizB283 I could definitely see avenues of improvement for that particular page, and I think an introduction on what the Developer Program is might be the key thing, but this is something I'll need to research a bit more. Better section titles would also go a long way towards improving it. "Scratch an itch" doesn't do much to tell me what's in that section.

Just so you know, though, we don't do tl;drs. Docs are here to be read. We do try to make them comfortable to read, but ultimately users have to be willing to read to use documentation effectively. There's no way around that, and they shouldn't be led to expect anything else.

I'm also not quite sure what you mean by "structured overview." There's a list of subheadings on the right, and the article barely fills the whole screen on my very compact laptop, so there's not a much scrolling happening. Elaborate on "structured overview" for me?

[OFFICIALlBAM81]

Peter needs to stop doing illegal merges without permission

[AzizB283]

Thank you so much for the thoughtful feedback!

You're absolutely right — the key issue with this page seems to be lack of clarity on what the Developer Program actually is. That insight is really helpful. Based on your notes and my experience reading the page as a user, here’s a refined list of the improvements I believe could enhance the article:

Clarifying the Need for Improvement

1. Missing Introduction / Purpose

The current opening line:

"If you build tools that integrate with GitHub, you can join the GitHub Developer Program."

…doesn't explain what the program actually is, what it offers, or why a developer should care.

Suggested improvement: A short paragraph that defines the program clearly — is it a community? a benefits system? an official directory? Knowing that helps the user understand if it's relevant to them.

2. Section Titles Could Be Clearer

As you noted, headings like:

• "Scratch an itch"
• "Take on the enterprise"

…are clever but ambiguous. They don’t explain the section content at a glance.

Suggested improvement: Rename to more explicit titles like:

• "Build GitHub-integrated Tools"
• "Test on GitHub Enterprise Server"
• "Promote Your GitHub Integration"
• "Eligibility & How to Join"

These would help users instantly understand what each section covers.

3. Structured Flow of Information

You're absolutely right — the page isn’t long. What I meant by a "structured overview" is more about logical flow, not length:

• What is the program?
• Who is it for?
• What are the benefits?
• How to join?
• What happens after?

Currently, those answers are spread out or implied, but not laid out clearly. We can improve that by making the structure more purposeful.

4. TL;DR Clarification

Thank you for the clarification on TL;DR not being part of GitHub's documentation philosophy. I completely understand now. My intent was to help users quickly grasp the page's value, but I respect the style choice to encourage full reading with a readable structure instead.

What I'd Like to Propose

If it aligns with the team’s roadmap, I’d love to open an issue that:

• Focuses specifically on improving clarity and readability.
• Proposes updated section titles and a revised intro.
• Maintains all existing content — just refactors layout and language to be more direct.

Please let me know if you'd like me to open that issue and include a sample outline to review. I'd love to continue contributing in a way that fits GitHub Docs' goals and voice.

Thanks again for your time and guidance!

[Sharra-writes]

@AzizB283 I actually asked around about this while I was waiting for your reply, and this entire program is a legacy thing currently owned by one guy in the organization. I need to check in with him to find out if any of this even relevant anymore, or if the whole article should be deprecated.

If it's still relevant, bringing it up to the standard of the current docs (it's really old) is high on my to-do list. I can never give exact timelines, but today is a holiday in the US and a lot of people have also taken tomorrow off, so don't expect immediate turnaround, but I'll check in with him when I can.

Ah, edit to add: about the tl;dr, one of my colleagues put it like this, which I thought was a great articulation, instead of a tl;dr, the introduction should answer "why should I read this?" or "under what circumstances would it help me to read this?"

[AzizB283]

Thank you so much for the clarification, and I really appreciate you checking internally and sharing the context about the Developer Program being a legacy piece.

Totally understand the delay, especially with the US holiday — no rush at all. I'll hold off on further changes until you’ve had a chance to confirm with the owner of the program.

Also, thank you for the TL;DR insight — I love that reframing: instead of a TL;DR, aim to answer “Why should I read this?” in the introduction. That makes a lot of sense and helps me understand the voice and goal of GitHub Docs better.

Looking forward to hearing more once you’ve had a chance to check in. I'm happy to help with improvements when the time is right!

[Sharra-writes]

@AzizB283 I reached out to the person who is in charge of this program, and it seems the program is going to be incorporated into a different program, and these docs are going to be deprecated, since they'll no longer be relevant. I've been hoping he'll get back to me with more details, but between vacations and him being busy, we haven't had a chance to talk about it more.

The important part is probably that the docs are going to be deprecated, so fixing them up isn't useful. I'm going to close this issue out, but if he ever gets back to me with information on the new program, I'll ping you in a comment to give you links to whatever resources I can, if that would be helpful.