10 ms·

I'd like to review your README

336 points by edward 6y ago

kstenerud 6y ago
I'd be curious to know how many takers he gets in the first day after being featured on HN!
- purplecats 6y ago
  The population size of HN seems much smaller than I originally had imagined.
witcher 6y ago
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?
- zakki 6y ago
  A template of a README with an example of outstanding README may help on wider scale.
rwmj 6y ago
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.
sfvisser 6y ago
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.
- globular-toast 6y ago
  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.
- jka 6y ago
  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.
- DandyDev 6y ago
  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.
  - Y-bar 6y ago
    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.
  - nooyurrsdey 6y ago
    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.
cpursley 6y ago
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.
jka 6y ago
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.
rmetzler 6y ago
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.
tirrex 6y ago
It would be great if author points us a few READMEs he likes. So, people can avoid many issues before asking for review.
- hakre 6y ago
  Also the record of readmes and their date when reviewed would be very insightful.
- remoquete 6y ago
  This. Or, you know, some sample pull requests he created.
mxcrossb 6y ago
> 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.
polote 6y ago
> 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 ?
- ChrisMarshallNY 6y ago
  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-world-activity-6775139604946329600-4DcC/ 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.
- deleted 6y ago
  [deleted]
- littleninja 6y ago
  > Does anyone know a community where one can find people to help individually ? Yes! https://codingcoach.io/ 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.
DandyDev 6y ago
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.
- nabla9 6y ago
  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.
  - hakre 6y ago
    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.
- nickjj 6y ago
  > 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 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 https://www.dropbox.com/about but it still doesn't come close to explaining what they do.
  - tmotwu 6y ago
    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.
teddyh 6y ago
The rules for traditional README files are documented here: https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp... https://www.gnu.org/prep/standards/standards.html#index-README-file https://www.gnu.org/prep/standards/standards.html#index-READ...
nickjj 6y ago
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/ 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.
- sundarurfriend 6y ago
  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.
hobofan 6y ago
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.)
ttty 6y ago
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. I'm willing to spend an hour per project, in total. I choose which projects to work on and how many projects. A README should have an example of how to typically use the software. It should say how the copyright and other legal aspects affect the project. A README can also contain instructions for installing the software, or how to run its test suite.
ozzmotik 6y ago
I think I need a README for writing a proper README.
noxer 6y ago
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.
- franciscop 6y ago
  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/documentation/options/README.md#public https://github.com/franciscop/server/blob/master/docs/docume...
- kstenerud 6y ago
  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-usage https://github.com/kstenerud/go-concise-encoding#library-usa...
- Gadiguibou 6y ago
  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 https://doc.rust-lang.org/rustdoc/documentation-tests.html
  - Omin 6y ago
    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 https://github.com/livioribeiro/cargo-readme.
jjjjjjjj1 6y ago
Be careful: An Email Account linked to README and public repository is considerable as privacy information.
- jjjjjjjj2 6y ago
  Yes. I agree.
cdubzzz 6y ago
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=2019-12-31 https://github.com/reallinfo?tab=overview&from=2019-12-01&to...
- ChrisMarshallNY 6y ago
  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).
- m463 6y ago
  > 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.
tyingq 6y ago
"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 ;)
yboris 6y ago
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%.
- MaxBarraclough 6y ago
  > 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.
- daptaq 6y ago
  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).
  - asutekku 6y ago
    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.
    - daptaq 6y ago
      IMO a valid, human readable README file is will always also generate readable rendered output.
  - atleta 6y ago
    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.
deleted 6y ago
[deleted]
mellosouls 6y ago
The generous author's gitlab page fwiw for examples of his own (it wasn't clear from the article): https://gitlab.com/larswirzenius https://gitlab.com/larswirzenius
nandi95 6y ago
I wish some people did that but for documentation
einpoklum 6y ago
Won't this fellow's queue fill up for months once this link is posted here on HN?

336 points by edward 6y ago

kstenerud 6y ago

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

purplecats 6y ago
The population size of HN seems much smaller than I originally had imagined.

witcher 6y ago

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?

zakki 6y ago
A template of a README with an example of outstanding README may help on wider scale.

rwmj 6y ago

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.

sfvisser 6y ago

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.

globular-toast 6y ago
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.
jka 6y ago
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.
DandyDev 6y ago
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.
- Y-bar 6y ago
  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.
- nooyurrsdey 6y ago
  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.

cpursley 6y ago

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.

jka 6y ago

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.

rmetzler 6y ago

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.

tirrex 6y ago

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

hakre 6y ago
Also the record of readmes and their date when reviewed would be very insightful.
remoquete 6y ago
This. Or, you know, some sample pull requests he created.

mxcrossb 6y ago

> 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.

polote 6y ago

> 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 ?

ChrisMarshallNY 6y ago
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-world-activity-6775139604946329600-4DcC/ 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.
deleted 6y ago
[deleted]
littleninja 6y ago
> Does anyone know a community where one can find people to help individually ? Yes! https://codingcoach.io/ 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.

DandyDev 6y ago

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.

nabla9 6y ago
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.
- hakre 6y ago
  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.
nickjj 6y ago
> 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 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 https://www.dropbox.com/about but it still doesn't come close to explaining what they do.
- tmotwu 6y ago
  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.

teddyh 6y ago

The rules for traditional README files are documented here: https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp... https://www.gnu.org/prep/standards/standards.html#index-README-file https://www.gnu.org/prep/standards/standards.html#index-READ...

nickjj 6y ago

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/ 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.

sundarurfriend 6y ago
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.

hobofan 6y ago

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.)

ttty 6y ago

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. I'm willing to spend an hour per project, in total. I choose which projects to work on and how many projects. A README should have an example of how to typically use the software. It should say how the copyright and other legal aspects affect the project. A README can also contain instructions for installing the software, or how to run its test suite.

ozzmotik 6y ago

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

noxer 6y ago

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.

franciscop 6y ago
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/documentation/options/README.md#public https://github.com/franciscop/server/blob/master/docs/docume...
kstenerud 6y ago
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-usage https://github.com/kstenerud/go-concise-encoding#library-usa...
Gadiguibou 6y ago
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 https://doc.rust-lang.org/rustdoc/documentation-tests.html
- Omin 6y ago
  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 https://github.com/livioribeiro/cargo-readme.

jjjjjjjj1 6y ago

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

jjjjjjjj2 6y ago
Yes. I agree.

cdubzzz 6y ago

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=2019-12-31 https://github.com/reallinfo?tab=overview&from=2019-12-01&to...

ChrisMarshallNY 6y ago
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).
m463 6y ago
> 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.

tyingq 6y ago

"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 ;)

yboris 6y ago

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%.

MaxBarraclough 6y ago
> 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.
daptaq 6y ago
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).
- asutekku 6y ago
  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.
  - daptaq 6y ago
    IMO a valid, human readable README file is will always also generate readable rendered output.
- atleta 6y ago
  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.

deleted 6y ago

[deleted]

mellosouls 6y ago

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

nandi95 6y ago

I wish some people did that but for documentation

einpoklum 6y ago

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