Hacker News Reader

Comment by protoman3000 | Hacker News Reader

The github repo of hubris [0] is very nice, as they immediately tell you where what is, e.g.

   drv/ contains drivers, a mix of simple driver lib crates and fully-fledged server bin crates. Current convention is that drv/SYSTEM-DEVICE is the driver for DEVICE on SYSTEM (where SYSTEM is usually an SoC name), whereas drv/SYSTEM-DEVICE-server is the server bin crate.

Why does nobody do this in their readmes normally? They just let you look into their code and tell you "now figure it all out yourself".

[0] https://github.com/faithanalog/hubris/tree/pinetime

View on HN

I've never understood why github shows the first line of the most recent commit for files / folders next to their name instead of the first line of any README.md file inside the folder.

Even on projects that I'm actively working on, the most recent commit of a folder gives me no useful information, whereas if I could edit the README.md I could atleast add a description of each folder so that new users could understand the directory structure better.

Same thought; I would love if there were a way to toggle between "latest commit message" and "first line of documentation for the file", depending on whether it's a familiar project or a new one I'm browsing.

In Rust, it's because most projects follow the default layout, and so is less needed.

We have a custom build system on top of Cargo, and so things are a bit weird for a normal Rust project, and so it's extra important.

> Why does nobody do this in their readmes normally? They just let you look into their code and tell you "now figure it all out yourself".

I think it's worth praising this repo without knocking others. Open source authors have no obligation to their users; if they don't have the time to, or just don't care to, so organise their READMEs, then they need not. In fact, if it's sufficiently important, for much open-source software anyone else can do it, and submit a patch.

This isn't just about open source. Developers on internal projects should do this too, but don't.

Have you ever tried to write useful documentation? As a programmer you are far to close to the code. You assume things are obvious that are not, while going into great detail describing things that are obvious (or maybe not obvious, but only rarely interesting and so should be documented in a deeper link not the main documentation). Or worse because you have to document it you document the code lines (++i; // increment i by one).

This is a hard problem. I try to make an effort, but too often I get it wrong.

Of course I have. And of course I recognize that writing good docs is difficult.

I am not talking about the difficulty of writing high-quality explanatory prose. I'm talking about expanding what people consider standard practice, to include a bullet-point description of how the files in the project are laid out. You don't need to be a good writer in order to do this.

That said, just because something is hard doesn't mean it's not a skill that can be learned. Not everyone has the same attitude for writing (much like programming), but generally I believe that "most people can be taught most things to a basic level of competence", and I do not think documentation writing is exempt from that principle. There is no reason why the skill of writing halfway-decent documentation should not be taught in programming courses.

Reply on news.ycombinator.com