[HN Gopher] How to write a great README
___________________________________________________________________
How to write a great README
Author : drako999
Score : 143 points
Date : 2023-07-18 14:34 UTC (8 hours ago)
(HTM) web link (www.appsmith.com)
(TXT) w3m dump (www.appsmith.com)
| slily wrote:
| I hate going to a project's GitHub page and seeing so much fluff
| and unnecessary or redundant information concealing the things
| that actually matter. If you want to show off, please do it on a
| separate website.
|
| I want to know what it is, how to use it, how to
| build/install/deploy it, and any other specific requirements.
| Everything else can easily be moved to a wiki page (in
| moderation, no "wiki mazes"), or simply separate files. And for
| god's sake keep your gaudy emoji spam away from me.
| bbno4 wrote:
| I have taken quite a few github projects to popularity and even
| written[0] about it
|
| GitHub does not support centreing images so you have to use HTMl.
| One tip I'll add is to avoid as much HTMl as possible so if
| you're in the terminal you can actually read it
|
| [0] https://skerritt.blog/make-popular-open-source-projects/
| rlnorthcutt wrote:
| This really stood out for me: 'We also think it is beneficial to
| show instead of tell wherever possible. We recommend using icons,
| images, and GIFs to keep it visually engaging and provide visual
| signposts -- helping readers quickly navigate to the details that
| are important to them.'
|
| We know that things like bulleted lists, headings, and paragraph
| structure can have a massive impact on readability... and I think
| those visual touches go even further.
|
| Of course, just using icons doesn't do anything (And can make it
| worse), but if they are relevant, then it adds another layer of
| data. +1 on images and Gifs - I find it much easier to evaluate a
| project if I have some idea of what it looks like (Assumign it
| has a UI).
| m-hilgendorf wrote:
| It can also make your project inaccessible if you rely too
| heavily on images.
|
| Personally I don't like too many images in a README. It's not a
| SHOWME. That's for your product page.
| rlnorthcutt wrote:
| True - but not every project is a product. I run across open
| source projects all the time where the README _is_ the
| product page. In those cases, I appreciate some images which
| can help me figure out if I want to try it out.
|
| Otherwise, I have to install or set it up just to preview it,
| and I will personally not do that most of the time. So, I
| appreciate some images when they help me evaluate the
| project.
| spacebanana7 wrote:
| I like using mermaid diagrams [1] in readme files and docs.
|
| They're easier to read than plain text explanations for
| architectural layouts/customer journeys but easier to modify
| than images and GIFs.
|
| Also natively supported in many flavours of markdown like
| Gitlab.
|
| [1] https://github.com/mermaid-js/mermaid
| hbcondo714 wrote:
| Same here, I like Draw.io but just did a sequence diagram
| showing a Stripe integration with actors, activations and
| notes in a few lines of Mermaid markdown on a GitHub readme:
|
| https://github.com/hbcondo/revenut-web#-workflow
|
| But that diagram just renders as code for the same readme via
| GitHub Pages:
|
| https://revenut.com
| eatonphil wrote:
| To me, too much use of icons, images, and GIFs sort of looks
| spammy. But I think there's a middle-ground where you just use
| images to help explain the architecture and a GIF to show a
| demo but you don't go overboard with it all.
| rlnorthcutt wrote:
| I totally agree - moderation is a good thing
| hiatus wrote:
| Are you really shilling for the project without disclosing your
| affiliation?
|
| https://github.com/rlnorthcutt
| [deleted]
| rlnorthcutt wrote:
| My apologies - it was a quick comment between calls :D In
| full disclosure, I'm the Head of DevRel at Appsmith. I didn't
| write this article, or contribute to it.
|
| That being said, I do think its helpful, and I like the fact
| that other projects' READMEs are noted as good examples too.
| yboris wrote:
| Please include a _screenshot_ if it 's ever appropriate. You will
| save your visitors so much time!
| lbhdc wrote:
| I feel like this has good intention, but I think it misses key
| information that should be in the readme.
|
| Its really great to have a blurb about what the thing does, the
| big idea behind why it exists, and how it fits into the rest of
| the universe.
|
| I also really want instructions for how to build the repository.
| It seems like that is really downplayed in this guide. I feel
| like that is misaligned with the target audience of those
| visiting the repository. I would rather sacrifice overview for
| instructions on how to use the thing.
| drako999 wrote:
| That was an intentional decision we took because we realised
| that the majority of users struggled to grasp the concept
| behind the project and how to use it. We didn't feel that we
| were ready to optimise for contributors yet :)
|
| Good point about mentioning why it exists!
| lbhdc wrote:
| Totally fair, and I agree contributor docs generally make
| more sense to be in their own document. That is how I feel I
| have seen most repos handle those docs.
|
| I was thinking less about contributors, and more about
| someone who just wants to use your project locally. Spin it
| up, try it out.
|
| Scanning through the appsmith repo, I don't see any files
| that jump out to me as documentation on how to build and run
| it. So it seems I would need to dig through the build system
| to discover what runnable things are in there. I would
| probably have to look at some application code to figure out
| what kind of storage it wants to talk to and how to configure
| that.
|
| That is a lot of work to give it a test drive. I assume this
| is to keep some moat for the saas offering, but that dx makes
| me less likely to consider exploring it to begin with.
| drako999 wrote:
| Hey everyone, I'm a co-founder and CPO at Appsmith. I have used
| this article to share our experiences with writing a great
| README, and I think it would be beneficial to hear about
| everyone's experiences with what actually makes a README useful
| for an open source project. Would love your feedback on the
| topic. And of course, if you have any feedback on how we can make
| Appsmith's README more useful for you, please let us know!
| juujian wrote:
| Love the write-up, I only have one question. What actual work
| were you procrastinating on by writing it ;)
| [deleted]
| drako999 wrote:
| Most likely, replying to user queries :)
| bityard wrote:
| There was no procrastination, this is called "content
| marketing."
| dcow wrote:
| One spot where your readme misses the mark: it can't be read
| outside of github (or some rendering engine). Markdown is
| supposed to be human readable. Instead you say "here's how app
| smith works" and then plop a big image. That doesn't help
| anybody understand what your project does by reading the
| readme. Images and diagrams are super helpful, but they should
| accompany thoughtful prose. This is also important as an
| accessibility consideration.
|
| Next, contributors sections are dumb. Github is a better tool
| to use to view contributors
| (https://github.com/appsmithorg/appsmith/graphs/contributors).
| Other projects before github would have an authors and/or
| contributors file. I don't care about the contributors when I'm
| trying to understand how your project works, it's just
| shameless marketing in that position.
|
| Finally, you have a "getting started in 100 seconds" image CTA
| in your _features_ section. Doesn 't make any sense to me and
| again there's no supporting text.
|
| Overall I'd suggest focusing on improving your readme to be
| more useful and less of a marketing tool (it can still market
| its value lightly) and instead explain how the software works
| and how to get up and running with it.
|
| Overall I'd score your readme 4/10.
|
| Edit: here's a readme to compare/contrast with
| https://github.com/Lxtharia/minegrub-theme
| ShadowBanThis01 wrote:
| Also: Don't use Markdown. Yes, it's "human-readable," but
| it's full of code text and there are almost no stand-alone
| VIEWERS for it.
|
| The rampant use of Markdown while there's a lack of viewers
| for it is baffling. And no, I don't count editors in which
| you can invoke a "preview" of the Markdown. Why publish in a
| format that must be loaded into an editor and then
| "previewed?"
|
| You might as well just use plain text, since the reader is
| just going to be seeing the raw text of the file anyway.
|
| Or have stand-alone viewers (not editors) for Markdown
| proliferated since I last checked a couple years ago?
| dcow wrote:
| I think markdown reads very nicely in text form.
| Title === Summary of the page
| # H1 Intersting Topic The most important
| part of [1] is... ## H2 What others say
| > Quote from somebody. Callout something.
| And then it's implemented like: ```
| // this code is a demonstration of how to query foo
| func foo() { does_thing(); } ```
| # Conclusion You should use markdown to
| structure your documents. [1]:
| https://example.com
| ShadowBanThis01 wrote:
| I said yes, you can read it. But I also noted that it's
| riddled with ## and other junk that doesn't do anything
| beneficial because you're seeing plain text. So why have
| detracting, non-informational characters in there?
| timetraveller26 wrote:
| *A self proclaimed great README
| sedatk wrote:
| I was gonna say... what's the benchmark they used to decide
| it was great? Did they win the best README award somewhere?
| yonasb wrote:
| Great guide. One thing that seems to be missing is something I
| see in a lot of README's: a list of the core tech stack being
| used in the repo. Good examples here https://github.com/undb-
| xyz/undb#-tech-stack and here https://github.com/steven-
| tey/novel#tech-stack. Did you already consider adding this as
| part of the guide and decide against it, or was it just not
| something you thought to add?
| avgcorrection wrote:
| > https://github.com/appsmithorg/appsmith
|
| That is more of a GitHub landing page than a readme.
|
| > An effective README file needs to tell your audience what your
| project does, how to use it, and how they can help out.
|
| The readme starts with an `a` image tag nested within a `p`.
| coobird wrote:
| My thought as well.
|
| If every project started to make their README filled with HTML
| (gah, why does Markdown allow arbitrary HTML...), I'd end up
| crying on the CLI as I frantically search for how to build the
| project in a sea of <p>, <a> and <br/>s...
| atoav wrote:
| Quite frankly I was happy with the arbitrary html part more
| often than it annoyed me. E.g. when I had to add a table that
| was just slightly out of markdowns comfort zone (merged
| cells).
|
| Those who read my readmes were always happy with the content
| and never complaines about the html.
| avgcorrection wrote:
| > gah, why does Markdown allow arbitrary HTML...
|
| MarkDown is a misleading name.
| dcow wrote:
| Yep, the author of their readme is more interested in marketing
| their product than explaining how to get started using the
| project. It's honestly like the product person wrote the readme
| and not the engineers. And I consider that to be a pretty big
| red flag. At least, I'm not using the project any time soon
| because it's wasted my valuable time marketing to me instead to
| getting me straight to into the software. And it tracks me
| without my consent. Not a _great_ readme...
|
| 0. There are tracking links in the readme?!? Ugh gross! Zzz...
| oh and btw: this readme tracks you even if you don't click
| links [vomit-emoji]. There's a tracking pixel loaded at the
| very end: <img referrerpolicy="no-referrer-
| when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=841c3
| 402-679b-456d-b528-537480a57269" />
|
| 1. The Readme has images without accompanying text, so it can't
| be read in a text editor right after you've cloned the repo.
|
| 2. It's littered with useless information and noise when my
| main goal of reading the readme is to get up and running
| quickly with the project. The contributors section is one
| example (and I mean just look at the source and try not to
| laugh): I can click the contributors link in github if I want
| to see that stuff, and an authors/contributors file is a better
| spot for that info regardless (and really you spent time on a
| bot for that). Further, the "getting started in 100 seconds"
| image-only link is in the features section with no accompanying
| text and there's a getting started link in the contributors
| section, they kinda get lost in the noise.
|
| 3. There's just one link to the documentation and it's pretty
| far down. I'd recommend linking to it much much earlier so
| users who just want to get started aren't wading through all
| the marketing gifs.
|
| 4. I don't think this readme is GDPR or CCPA compliant... but
| IANAL.
|
| Generally, a readme isn't a replacement for a marketing website
| especially for a product company. Maybe for a small open source
| entirely community driven effort most of their touchpoint will
| be a readme. But there's nothing organic about this readme,
| it's full of marketing fluff, tracking links, testimonials via
| contributor bubbles, and very little explanation of how app
| smith works, how you get started, example code, etc. Here's an
| example of a project with a really great readme:
| https://github.com/Lxtharia/minegrub-theme (it's just one of
| the other interesting links on HN today as well). And here's
| another one: https://github.com/stateful/runme.
|
| Not trying to be too harsh, it's an okay middle of the range
| readme all things considered. But is it _great_? ..Meh.
| mgbmtl wrote:
| I love the "Steps: 1 - 2 - 3" image. It reminds me of the old
| Slashdot memes of: * Step 1: collect underpants
| * Step 2: ?? * Step 3: Profit!
| distcs wrote:
| Since we are on this topic allow me to do an Ask HN comment here.
|
| Ask HN: What are some good Readmes you have found?
| hinnisdael wrote:
| vidstack is very light on technical details but starts with a
| concise intro and a screenshot, as well as relevant links:
| https://github.com/vidstack/player
|
| payload is well-structured in general:
| https://github.com/payloadcms/payload
|
| nanostores starts out with an intro and telling code examples,
| followed by lots of technical details:
| https://github.com/nanostores/nanostores
| zubricks wrote:
| We really appreciate the shoutout on our Payload readme! We
| put a lot of effort into making it impactful and useful for
| our community.
| oslem wrote:
| Quick plug for makeareadme.com. I've always found it to be a good
| starting point for new projects.
| andai wrote:
| https://www.makeareadme.com/
|
| (clickable link!)
| KronisLV wrote:
| There's also this site which has a few different README
| templates: https://www.readme-templates.com/
| zuckerborgggg wrote:
| [flagged]
| fbergen wrote:
| For a different take. Have a look at runme.dev
| johanneskanybal wrote:
| tl;dr although my first principle is good readme files.
| teddyh wrote:
| Here are the _traditional_ best practices of how README files
| should look:
|
| "The distribution should contain a file named README with a
| general overview of the package:
|
| the name of the package;
|
| the version number of the package, or refer to where in the
| package the version can be found;
|
| a general description of what the package does;
|
| a reference to the file INSTALL, which should in turn contain an
| explanation of the installation procedure;
|
| a brief explanation of any unusual top-level directories or
| files, or other hints for readers to find their way around the
| source;
|
| a reference to the file which contains the copying conditions.
| The GNU GPL, if used, should be in a file called COPYING. If the
| GNU LGPL is used, it should be in a file called COPYING.LESSER."
|
| -- GNU Coding Standards,
| https://www.gnu.org/prep/standards/html_node/Releases.html#i...
| (July 1, 2021)
|
| "Good things to have in the README include:
|
| 1. A brief description of the project.
|
| 2. A pointer to the project website (if it has one)
|
| 3. Notes on the developer's build environment and potential
| portability problems.
|
| 4. A roadmap describing important files and subdirectories.
|
| 5. Either build/installation instructions or a pointer to a file
| containing same (usually INSTALL).
|
| 6. Either a maintainers/credits list or a pointer to a file
| containing same (usually CREDITS).
|
| 7. Either recent project news or a pointer to a file containing
| same (usually NEWS)."
|
| -- Software Release Practice HOWTO,
| https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...
| (Revision 4.1)
| [deleted]
| KnobbleMcKnees wrote:
| Please for the love of Cthulu remove that awful auto scroll from
| your homepage. It's practically unusable in a mobile webview.
|
| Great article though!
| lopkeny12ko wrote:
| +1 this is awful. I thought there was something wrong with my
| browser!
| drako999 wrote:
| Thank you for the feedback! We'll fix it :)
___________________________________________________________________
(page generated 2023-07-18 23:01 UTC)