I'd like to review your README | Hacker News Reader

I'd like to review your README

liw.fi

336 pointsedward89 comments

Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place.

Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.

I'm so lost when looking at READMEs or web pages like that. It will tell me that it's going to solve my problem faster and better than all other solutions out there. But I still don't know what my problem is.

Always start with the problem. Tools don't exist just for fun, they exist because we need them.

In some cases it is valid for a project to write for a particularly niche audience; it may be difficult to write for everyone. But yep, sometimes they may simply need help improving their messaging.

To be fair, I think we're talking about READMEs for technical projects here, probably hosted on Github/Gitlab/... And in that context your example is totally clear to me: it's a framework for running (background) jobs asynchronously (i.e. code that does not need to run on the main thread of your program and block) and you can use it both on the server and the browser (so probably JS/TS) and it's not intended to be feature rich.

I'm not the person you responded to, but I think their peeve stands correct for technical README's as well. I've decided more than once to not continue reading those when is is not clear to me to move on to what might be a similar implementation just because the README never really explained if it was what I was looking for.

The times when I need to read the repo README is when I am not familiar with what I am looking for. I say err on the side on more documentation, err on the side of a better explanation.

Sure the individual words make sense but there's a cognitive load of deciphering that when you're first trying to learn something.

A "plain english" no nonsense definition goes a long way to introduce your concept. Save the fancy technical jargon for further down in the README if you must.

You have a point and I might reprioritize.

Specialized terminology allows the communication of complex concepts compactly. For the specialists a brief description like you mentioned is perfect. If you give it first, that person can read it and decide.

It should certainly be followed by a tear down or other plain English explanation of what the thing is.

Kind of like: ``` Brief

A little longer

Be descriptive about the thing

Go into every detail you want to discuss about the thing in the repository... ```

The jargon fooled blurb makes a great "a little longer" and gets out of the way to let the more readable description be given. Burying that can be a pain.

That's a really good point.

I need to either find or write a good readme template with that in mind.

A lot of asynchronous job frameworks run workers on many machines across a cluster. That's a very different sort of framework than one that runs things in the background on a single machine, but the short description applies equally well to it.

fast, simple, scalable, modern, high performance, easy to use, enterprise-grade, secure, production-ready, new generation, lightweight ...

These are common words I see in the first paragraph of readmes. If people can avoid these, they’ll write better introductions. No marketing, no subjective words. Otherwise, I feel like someone is trying to sell me that product.

I agree in general, except for `production-ready` which I deem useful information. Of course, it is only the maintainers‘ assessment on the state of the project and thus needs to be validated further by myself. But IMO that adjective signals that I can expect the author to be happy with the current API and behavior and can assume it will be relatively stable; probably battle-tested.

I think "production ready" is essentially impossible without also being able to say "I/my employer/foocorp is running this in production" unless you're not allowed to say it for legal reasons. I think it would take a very experienced developer to predict in advance every issue they'd run into putting something into production.

The definition you gave is exactly how I would read `production-ready`. I might be overly optimistic in assuming that this is the case whenever someone uses the term, though.

> I think it would take a very experienced developer to predict in advance every issue they'd run into putting something into production.

I am not sure whether that can be expected from any project that exceeds a very narrow scope and/or if which it’s correctness can potentially be mathematically proven.

This sounds right, though it doesn't have to be. These type of words signal the author's intent and when 1 - justified by the actual deliverable 2 - substantiated with concrete data can be very useful. They can help create the right expectation. Unfortunately, they are more often misused or abused than applied correctly.

> These type of words signal the author's intent

How many people intend to make slow, outdated, insecure software?

> when 1 (…) substantiated with concrete data

Then show me the data and let me reach my own conclusions. As a bonus point, the unquantifiable adjectives will be removed.

> Unfortunately, they are more often misused or abused than applied correctly.

Which makes them useless all of the time, because by now we’re primed to ignore those claims.

> How many people intend to make slow, outdated, insecure software? The point is that some authors may claim simplicity, some may claim performance, others more security and so on. It is rare to have all adjectives thrown in - and easy to discard when you see them.

>because by now we’re primed to ignore those claims. Unfortunately, we don't always. If we were ignoring them all, then we wouldn't care. It is that we can't help read and interpret them and have our expectations set up; hence the disappointment when it turned out to be just words.

I think production ready on its own has value because it sets the stage of what to expect.

There's a very big difference between a project being production ready or not. Production ready (to me at least) means the project has been thoroughly tested on a live site and is in a position where you can take it as is and run it in production with confidence that it's going to work.

For example I have a Docker + Flask example starter kit project at https://github.com/nickjj/docker-flask-example and the GitHub description is "A production ready example Flask app that's using Docker and Docker Compose.". In this context to me that says it's using multi-stage builds, env variables, deals with static files in a way that's cacheable (md5 hashes, etc.), has tests and overall you can expect to see patterns that work well in both dev and prod. The README goes over those details too in case you didn't infer that from only "production ready" too.

Plot twist: It took me longer to write the README than create the whole project.

I'd expect a fast json parser to be harder to use than an easy-to-use or simple one. But if I need to eke out maximum performance on something I'm going to skip the ones that don't have fast in the description - it means the project's goals aren't aligned with my use case. If it's a web project then I'm going to focus on parsers that have have actually considered security over the ones that haven't.

These are all important words for describing projects.

You forgot to add military-grade encryption and cloud-native tags

Fast is not a KPI though. It can and is often labeled on anything, making the term useless even when fast is a criteria over ease of us.

Maybe something at the top along the lines of : what it does, how and then what are the implications.

Claiming "fast" implies that performance is a project goal, possibly even tracked over time as a metric, and that there's probably a comparison deeper in the README or elsewhere. It probably also means that when it comes to tradeoffs (compile time, code size, binary size, ergonomics, maybe even strictness/correctness), runtime speed is the preferred option.

"[description], aimed at speed" or something like that is better in that case, IMHO.

Code for asynchronous work, but it's isomorphic whatever that means.

Nodejs

Here's my README pet peeve: When the examples for some tool that operates on source code show it operating on its own code.

As a reader unfamiliar with a project, it's unpleasant to have to contend with "meta" at a time when one doesn't even have a solid first-order understanding of the project.

prism.js the code syntax highlighter is notoriously bad at this.

At first I felt bad for being confused by something so simple. But all their code examples for highlighting refer to their own code and you're right, at the exact moment you're trying to absorb new information it is infuriating to deal with the "meta" examples.

I don't use them out of that alone.

This is my main issue with Rspec documentation.

RSpec has none of that, a typical example from the first page of their documentation:

  RSpec.describe Widget do
    example do
      expect(described_class).to equal(Widget)
    end
  end

Pretty non-meta.

I really appreciate folks who commit time to open source projects for things other than code (e.g. things that may be otherwise neglected).

There was a user on GitHub back in 2019[0] who went around and created logos for a bunch of projects (including one I was working on actively at the time). Out of curiosity I looked the account up recently while working on a new project but it's not longer active.

Translations are another great example of this. That same project that got the logo has also been translated by various people in to eight different languages!

Other ways I'd love to find people devoting time to smaller projects -- accessibility and UX audits. It's hard to account for all this stuff on smaller projects with only one or two primary developers.

[0] https://github.com/reallinfo?tab=overview&from=2019-12-01&to...

This.

Especially the localization bit. I'm constantly surprised to encounter folks that never even think about it, until version 1.5, and then find out that localization is a nightmare to add, after the fact.

And getting folks to work with them, is just as nightmarish.

Good RoT for localization is native, local speaker of the language, and dialects need to be considered. It's quite possible to bust your ass, getting a Spanish translation, only to have a lot of upset Latin-American users, because the translation was done in Castilian Spanish, as the only person who could handle the tech involved in localization was a CS student in Madrid.

I've learned to factor localization in from the beginning; even if I'm sure that this will never be used outside of my country (which isn't actually fair. There's neighborhoods in Brooklyn, where English is not the primary language; even though everyone was born here).

You just need to get to the point where you have to add localization after the fact –once, to get religion.

Localization is difficult and expensive. If we want people to help us localize, it is incumbent upon us to make it easy and relatively tech-free.

Or we can pay beaucoup bucks to iBabble-On (who do a great job, but not for free).

> accessibility and UX audits

I so very much agree. I think user interface design and inconsistency is really holding linux back. Accessibility is intertwined with it.

I think if someone who did game ui design paired with a blind person could critique linux distributions (that led to changes), we would all benefit.

I wish people would find a way to include any code present in a README in some kind of automated test.

Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated

Maybe not include any code is the better solution, instead add an example folder.

I did that! I hope you are not the person who suffered that from me (did you use Picnic CSS a few years back?). So for a newer project I put some setup code that will look for all code snippets with a specific comment and run that with the code after the comment. For generating the website documentation that test bit can be stripped (though I kept it for now).

Example: https://github.com/franciscop/server/blob/master/docs/docume...

One thing golang did right is the go playground. When I put code in my README, I also include a playground link.

Example: https://github.com/kstenerud/go-concise-encoding#library-usa...

That's included in Rust![1]

Code examples from the documentation automatically become "documentation tests" to make sure your examples are still up to date when updating your code.

[1] https://doc.rust-lang.org/rustdoc/documentation-tests.html

The README.md isn't part of the rust code, so it's not checked by this unless you use tools to generate your README from doc comments like https://github.com/livioribeiro/cargo-readme.

Actually, it's possible and even frequently used, for example in lazy-static, through the `doc_comment` crate.

    #[cfg(doctest)]
    #[macro_use]
    extern crate doc_comment;
    
    #[cfg(doctest)]
    doctest!("../README.md");

Now, the readme examples are tested like everything else.

https://github.com/rust-lang-nursery/lazy-static.rs/blob/mas...

I like this about elixir, in the documentation you can use exdoc to make sure that the code examples actually work, and provide code samples that are tested. It makes reading documentation for projects quite nice.

I've written this tool to test example code in markdown documents using user-specified shell commands: https://github.com/anko/txm I have had great success using it in my own projects, so perhaps others might find it useful too.

I do something similar: my README contains the output of --help, and I have a CI step that ensures that all the lines of the actual help output are present in the README. Caught me a couple times forgetting to update new flags and version changes.

I've spent hours putting that functionality into a unit test. Worth every minute!

This is brilliant!

It’s one of those things that’s so easy to forget or not even think about but once you see it or think about it, it’s essential.

Generate it with an m4 include.

This is great advice and I wish it was the standard. I had this problem on one of my projects so I used a githook to basically paste in actual compiled example files from the test suite on committing. It does mean the actual readme is more like a template and you can't edit the README file directly anymore but all the examples always work now!

I personally like at least one small example embedded in the README since it's zero effort, an example folder is great for _more_, but annoying to get started, what should I look at in the example folder first?

You'll like this https://kodare.net/2020/10/23/100_percent_coverage_docs.html it's my journey to 100% coverage for all code samples in ALL the documentation for iommi.

I've been using https://github.com/brodie/cram for this. It's a neat little shell testing tool that can be told to check that every 4-space indented markdown code block output what it says it outputs, so I just cram my README.md.

An example of this in action: https://github.com/liskin/liscopridge/blame/68a656b7beb10a5c..., https://github.com/liskin/liscopridge/blob/68a656b7beb10a5cd...

Beyond covering the "why" and the problem your tool solves it's also IMO a really good idea to include a "why use this over XYZ" section if your tool happens to have a few popular alternative libraries or is similar to something that most folks in your niche already knows.

Because if your tool is new, one of the first things folks are going to think is "why wouldn't I continue using XYZ?". The goal of this question isn't to put down the competition but it should draw comparisons between the tools and include the reasons why you created your tool. This could be adding certain features, doing things faster or whatever makes sense.

Flask-Classful's docs https://flask-classful.teracy.org/ has an excellent example of the above. The opening paragraphs cover it so well. The rest of the docs are also a good baseline example for creating useful documentation. Lots of practical code examples with very clear explanations of how it works.

Even without detailed comparisons, a "Related projects" section is very useful to the user. Sometimes I see such a section with comments on the other projects like "ProjectA: in case you want features X and Y", or "Project D: emphasises minimalism and configurability", and that is both immensely useful and increases my confidence in the current project whose README I'm looking at. It makes it clear that the author has your best interests in mind and understands their project's strengths and weaknesses.

If the repository is of an application, I strongly recommend people include a screenshot of it.

It blows my mind when someone has spent hundreds of hours to make something that they'd like others to use, and didn't spend the 5 minutes needed to increase its use by (my estimate) at least 5%.

> I strongly recommend people include a screenshot of it

Related: if your project has a website, include a screenshot on the front-page, not buried somewhere. A clickable thumbnail is fine, just don't make the reader work for it.

Might also be worth having a video of the application in action.

The issue here is that it is meaningless when viewed locally. GitHub made the mistake of turning "README", a file you'd usually read when you download some code into a website format. A README is broken if lines aren't broken, it is full of badges or nonsense like a table of contents (as OP says, a README is not a manual).

To be fair, i haven’t read a local readme in years. Markdown in github is hands down miles better and provides more value than any local readme openable with any kind of computer could provide.

IMO a valid, human readable README file is will always also generate readable rendered output.

It's not. You can include images in markdown and markdown being markdown, the links are pretty easy to identify and then open.

They don't have to, or better to say the shouldn't, be absolute http links. They can be just relative ones, and those will translate very nicely into file paths locally. If you just use a plain text editor you'll have to open them manually. A bit smarter one (e.g. most likely your IDE) will turn them into clickable file links. You're not losing anything but whoever looks at it on the web will have a lot better idea. And most people will look at it on the web first, before cloning the repo locally... Because it saves time.

A good README is unlikely to be 5 minutes of time. I've spent ~5 hours on what I consider "OK" READMEs for our internal projects where I have a captive audience (so don't need to sell them on it)

Adding a screenshot to a README would likely take about 5 minutes. Put your app over a white background, take a screenshot, trim it, paste it in a commend under "Issues" and copy the GitHub-generated shortcode/url for it.

Pasting to an issue to get an easy image upload is a nice trick, thanks!

At least one screenshot is nice. A demo video or GIF is amazing.

It would be great if author points us a few READMEs he likes. So, people can avoid many issues before asking for review.

Also the record of readmes and their date when reviewed would be very insightful.

This. Or, you know, some sample pull requests he created.

Many READMEs would be greatly improved with a one paragraph introduction to the topic, defining all the terms used and outlining the problem that the project is trying to solve.

> I’d like to help others make better free and open source software so I’m making this standing offer: I’ll review your README for free.

On a more global discussion, I feel like a lot of experienced people are willing to help, or teach for free on subjects such as, startups, programming, product management, data science, tech subjects ... (and I assume on other non-tech topics also) but it is always hard to find people to help. I mean you could join a charity, but it is not the same thing as being close to one person and helping him in topics he is not good at.

Does anyone know a community where one can find people to help individually ?

As an older person that has done quite a bit of free teaching, I'd gently suggest that a good start would be to have the current generation be a little more generous towards us.

A lot of us are, indeed, tiresome old "OK boomers," but some of us (I'd like to think I'm one) may actually have something to contribute.

Here's an example of a simple course I gave on Core Bluetooth. It was not free, but try! Swift World does their courses for $50 a pop, which is pretty cheap (BTW: I donated the proceeds for my class to sponsor scholarships to other classes): https://www.linkedin.com/posts/chrismarshallny_try-swift-wor...

Take note of the course materials. They basically teach the class on their own (also, they are entirely driven by some very intense READMEs).

In my experience, a couple of the better teachers on try! Swift World are relatively older ones, like Erica Sadun and Daniel Steinberg. Some of the younger ones are also excellent.

> Does anyone know a community where one can find people to help individually ?

Yes! https://codingcoach.io/

I enlisted to be a mentor but found I wasn’t prepared or ready for the time commitment quite yet. The folks who reach out are often in a bootcamp or self taught and looking for a way to break into their first tech job.

The rules for traditional README files are documented here:

https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...

https://www.gnu.org/prep/standards/standards.html#index-READ...

> A README is meant for someone who is first encountering the project to be able to quickly decide if they want to learn more about it.

In the past, by time I got to the readme I had already downloaded the project. It’s kind of weird how places like GitHub rendering the readme have changed the practice.

Great initiative and very generous!

My pet peeve with READMEs: usage of excessive adjectives to oversell your project. Famous culprits: "blazingly fast" or software that is "beautiful" or creates "beautiful" things.

People are starting to adapt corporate PR and marketing jargon as sign of professionalism.

Another way to make yourself appear silly influencer is to use words like "I" and "My" in headlines ("I made a thing", "My thing hobby", "My thoughts on .."). Obviously it's you. But people don't know who you are and generally they don't care. Pushing persona makes everything look like social media marketing.

And not only such. In the end this is how marketing works, there is always the feeling to be left: the feeling to be part of the in-group.

> My pet peeve with README

DHH had a funny line around Dropbox's "mission" in his 2019 railsconf video (linked to the direct point in the video): https://youtu.be/VBwWbFpkltg?t=2818

Dropbox's official mission as of 2019 was: "We're here to unleash the world's creative energy by designing a more enlightened way of working"

And DHH's remark was: "For fuck's sake Dropbox, you host files and make them appear on all of my computers"

Funny enough since then they changed their mission to be "Our mission is to design a more enlightened way of working" based on https://www.dropbox.com/about but it still doesn't come close to explaining what they do.

Customers don’t infer the purpose of a product from it’s company mission. The audience of a company mission are employees themselves. Dropbox has expanded to more than file syncing over the past decade. It makes sense to have a broad vision of their future, e.g purposeful mission.

Imagine Amazon telling employees to stick it to books because thats the business they started off with. Like why should AWS even exist, it’s not what they do! That narrow mindedness wouldn’t have gotten them to where they are today.

Zero people have looked at a mission statement like that and thought "Ah, now I understand the scope and limitations of my company, and will use that to direct my ideas".

> Customers don’t infer the purpose of a product from it’s company mission. The audience of a company mission are employees themselves.

ok sure then why is it in big red text on a customer-facing page, then?

It is a very good point. And the mission points to the future, where the management wants the company moving. It should not describe what it does, but where it is heading.

The generous author's gitlab page fwiw for examples of his own (it wasn't clear from the article):

https://gitlab.com/larswirzenius

Great initiative! Thank you for doing this, it's definitely nice from your side to spend time on community, especially if you have strong opinions on README look.

I wonder only, how to scale it (: Is there a way for anyone to help with this effort, while not spending O(n) time. Automation?

A template of a README with an example of outstanding README may help on wider scale.

I think that's a great service for projects that want more users (whether that's a good idea/goal is another topic)!

On my own projects I've seem a pretty clear divide in adoption between projects which have a good README (100+ stars) and projects which have a similar level of utility/maturity but where I didn't bother to write a proper README (0-5 stars). (Stars are often a bad proxy for adoption, but here they are roughly proportional to downloads, reported issues, etc.)

This is a great idea, and worth encouraging.

Some tips to be aware of in order to maintain a healthy contributor/maintainer ecosystem:

Bear in mind the volume of requests that the project/maintainers may have to deal with. This is usually fairly open and transparent with most FLOSS projects.

It's always good to test and understand your changes before submitting them - and if you can demonstrate that to the maintainers (by way of test coverage, screenshots, console output, etc), that'll increase the likelihood that your changes can be accepted, and can increase your reputation for respecting maintainer time.

If you feel like you _didn't_ fully test/understand your changes and they _were_ accepted regardless, that could be a sign that the project needs a bit more help with review and quality control. That can be a challenge, and it can also be an opportunity to provide other improvements (for example, by code reviewing and/or increasing test and continuous integration coverage).

PS: It might sound like a lot of this refers purely to code changes - but READMEs and documentation can be equally important to keep correct.

I'd be curious to know how many takers he gets in the first day after being featured on HN!

The population size of HN seems much smaller than I originally had imagined.

"Queue status, in case you’re waiting: 70 in queue, 6 reviewed, oldest in queue: 2021-04-15 13:30 UTC"

Guessing that queue is getting deeper now. Maybe he should add a nominal fee to jump the queue ;)

It's a really nice offer.

I found one small typo: "Part of the~~w~~ review process"

I'm sorry, it's kind of a trigger for me to read READMEs with typos and I need to send a PR to fix it.

I won't even consider projects who's READMEs don't include enough info on what it is and basic steps for bootstrapping it up.

I think I need a README for writing a proper README.

Won't this fellow's queue fill up for months once this link is posted here on HN?

I wish some people did that but for documentation

Be careful: An Email Account linked to README and public repository is considerable as privacy information.

Reply on news.ycombinator.com