[DOCS]: Please make your documentation readable by normal people

[pwillis-oi]

Describe the need

As a user, I'm trying to find something in octokit to use in my actions, but I can't find it. I can't find it because your documentation is incredibly obtuse.

If you go here (https://octokit.github.io/rest.js/), you get tons and tons of information. And there's a general sort of list of categories on the left, and sentences that describe use cases.

But it's impossible to just scroll through this and find the thing you're looking for.

• The layout is one fixed frame on the left, and a bigger window on the right. On the left frame are these long sentences that wrap, and there is no visual delineation between the sentences. So it's just a wall of text with seemingly no structure. You have to read every single sentence, and try to cognitively unpack this wall of text into a bunch of separate statements, then understand those statements, and figure out if it might give you what you want. (You won't really know until you click it and see what it's actually doing, though)

• A lot of the time it's not clear exactly where in this huge library is the thing that will give us what we want. Looking at the categories on the left, the thing I'm looking for could technically be in 5 of them, so I'm going to have to click through all of them, and read literally every single entry, because there is no way cognitively to skim them (see above).

• Assuming I knew in general what kind of "thing" I was looking for (some kind of function under octokit.rest.*), right now I have to ctrl+f for "octokit.rest.", and basically click "enter" continuously, to look for every instance of that string in the documentation. There's no place where I can just list all the function calls in one page/place and scroll through the list.

• Another thing that makes no sense, is where in GitHub, I can use what kinds of code, or variables, etc. Let's say I'm writing a GitHub Action that I want to comment on a PR and inject the URL to the current job results. There's no place to go to just get a list of what kind variables or objects etc that are available, and what their attributes are, or whatever. Right now I'm literally trawling through repos in GitHub searching for strings in your code, just to try to piece together my own documentation, so I know what's possible. Why do I have to go on a scavenger hunt just to find what all is available in your own product?

Honestly it's all just so daunting, I want to give up and use a different product. I wanted to like GHA. But if this is all I can expect, to have to crawl through barbed wire to figure out how to do one basic thing, it's not worth using. I'd rather use a much crappier product that I can understand without pain.

SDK Version

No response

API Version

No response

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀

[wolfy1339]

The docs website for @octokit/rest is due for a refresh, I can give you that.
There currently isn't a single overall tracking issue for the docs.
octokit/rest.js#433
octokit/rest.js#423

The docs, methods, and types are all automatically generated from GitHub's Open API spec. The docs are meant to give an overview on how to use @octokit/rest and what the methods are named, and the parameters.

You might be better off using the GitHub REST API documentation, and then cross-referencing the Octokit docs to get the function.