Hacker News Reader

Comment by wyattpeak | Hacker News Reader

I think it's strange to focus on all these details without addressing what seems to me the overwhelming problem with the GitHub layout - the deprioritisation of the readme. Why is it below the fold?

I was very confused for a considerable time when people would point me to GitHub for a description of a project, because there didn't appear to be a description, just a repo. Was I supposed to build it to see what it was?

This seems very silly in retrospect, but there really was a month or two where I just didn't understand at all what I was supposed to be doing there, and I've never forgotten it.

And why? Why is it so critical that the first thing people see is the file structure, and not a description of the project? Echoing the article, I suppose it makes it "about git", but even when I'm interested enough to start poking around, I'm more likely to clone a project than browse through it on the site.

It just feels intentionally obtuse.

View on HN

I mention this in a sibling comment, as I've thought something similar: maybe the README should be on top. The problem, as I mention there, is that when you use GitHub as a tool, it's more common to navigate to the files than refer to the README. And with long READMEs, that's potentially a lot of scrolling to get to the files.

What this implies is that GitHub is not your project page. The README there should be more development focused, and there should be a separate project page which goes into more detail about project-level things.

I missed your comment, it's better reasoned than mine and I think I agree with it.

I was just saying on another comment that I think the problem is GitHub, while maybe it shouldn't be, is the de facto project page for many projects, and is a major use-case.

There perhaps can't be a good solution - it's convenient enough that most small developers can't be bothered maintaining two different information sources about their work, and GitHub certainly has no reason to dissuade people from using it that way, but to prioritise the readme would make actually using the site harder.

Just one of those awkward things you live with, perhaps.

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.

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.

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.

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.

A small "Read the full description"-link to the #readme anchor below the inital short description probably would work wonders here.

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.

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.

You can use the #readme anchor to link directly to the readme, e.g. https://github.com/ruby/ruby#readme

Quite useful when you want to point people directly at the description.

I see what you're saying, but I think there are two major use cases for Github, one where the README should be first, and one where it should be last. The first is yours, visiting a repo, which often serves as de facto homepage for a project. The second though, is for projects you contribute to or use frequently, where finding out what's new or navigating to particular piece of code is the most important task. I'm not sure what a good way of distinguishing between the two would be.

> I'm not sure what a good way of distinguishing between the two would be.

GitHub Pages makes it easy to create a separate website for the first use case, which you can link to on the very top in the description. Then the README can contain info aimed at (new) developers of the project, build instructions and the likes, which you likely don't have to go to frequently (your 2nd case).

I had the same exact reaction as you when I first used Github. So I think Github's response to this problem is the whole Github.io domain. Those are supposed to be the project landing pages for the plebs while github.com domains are for developers.

It'd rather have it all in one place, with the landing page being the README, and the more developer focused info hidden in tabs, but that's not the current design unfortunately.

I've found a way to author project descriptions under the current layout using Org-mode. The trick is to leverage two features. One is that Github projects will use README.org files as a README file. For instance this is one of mine

https://raw.githubusercontent.com/geokon-gh/linearsystems-pa...

it shows up in the README spot https://github.com/geokon-gh/linearsystems-part2 and also in the Github.io https://geokon-gh.github.io/linearsystems-part2/

The rest of the magic is in the HTML configuration at the top of the file - particularly: #+EXPORT_FILE_NAME: index.html

So then when you export the document to HTML it turns into your Github.io root file. This way you can keep your dev-facing README and public facing Github.io page the same. It's a little ugly.. but it gets out of the way and works

Reply on news.ycombinator.com