4 ms·

As a developer, the README is useless, I am usually on a Github repo to start looking at code, and I don't want to have to first scroll through a README. IMHO

As a developer, the README is useless, I am usually on a Github repo to start looking at code, and I don't want to have to first scroll through a README. IMHO documentation websites and the like is where people should get their first feeling for a project, that is where the README should be.

wyattpeak 8y ago
That seems like a great idea in principle, but for most small projects the GitHub page /is/ the documentation. If that weren't the case, you wouldn't see half a dozen links to GitHub pages to show off projects on HN each day. It's all very well to talk about ideals, but you can't ignore reality in the process. You're right, though, that you shouldn't have to scroll past it every time. I don't really know what the solution is, but having it there but going undiscovered is the worst of both worlds.
- X-Istence 8y ago
  If you've read one README on Github, you know to scroll down to see it on every other project. I would argue that it's not a steep learning curve, and it's not like the hide the scrollbar... we scroll in other websites without issue when we are looking for content, especially with ads being most of the content above the fold these days.
  - wyattpeak 8y ago
    I agree it's not much of a learning curve, but neither is learning which icon represents a commit. This entire discussion is about minor details.
- DanSmooth 8y ago
  A small "Read the full description"-link to the #readme anchor below the inital short description probably would work wonders here.
snowe2010 8y ago
Hilariously I feel the exact opposite. I'll use OctoTree if I want to view the code, as github's code view is absolutely horrendous. It's like when your using Mac's Finder, it doesn't make any sense. I visit the main page of a repo to see the Readme or to go straight to the issues/prs page. I'll use OctoTree to view code.
- X-Istence 8y ago
  Using Github's tool for looking at the code tree is mainly so that I can grab a link and point someone to a line in a file.

wyattpeak 8y ago

That seems like a great idea in principle, but for most small projects the GitHub page /is/ the documentation. If that weren't the case, you wouldn't see half a dozen links to GitHub pages to show off projects on HN each day. It's all very well to talk about ideals, but you can't ignore reality in the process. You're right, though, that you shouldn't have to scroll past it every time. I don't really know what the solution is, but having it there but going undiscovered is the worst of both worlds.

X-Istence 8y ago
If you've read one README on Github, you know to scroll down to see it on every other project. I would argue that it's not a steep learning curve, and it's not like the hide the scrollbar... we scroll in other websites without issue when we are looking for content, especially with ads being most of the content above the fold these days.
- wyattpeak 8y ago
  I agree it's not much of a learning curve, but neither is learning which icon represents a commit. This entire discussion is about minor details.
DanSmooth 8y ago
A small "Read the full description"-link to the #readme anchor below the inital short description probably would work wonders here.

snowe2010 8y ago

Hilariously I feel the exact opposite. I'll use OctoTree if I want to view the code, as github's code view is absolutely horrendous. It's like when your using Mac's Finder, it doesn't make any sense. I visit the main page of a repo to see the Readme or to go straight to the issues/prs page. I'll use OctoTree to view code.

X-Istence 8y ago
Using Github's tool for looking at the code tree is mainly so that I can grab a link and point someone to a line in a file.