How to write a great README(appsmith.com) |
How to write a great README(appsmith.com) |
“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)
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`.
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=841c3402-679b-456d-b528-537480a57269" />
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.
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...
Those who read my readmes were always happy with the content and never complaines about the html.
MarkDown is a misleading name.
* Step 1: collect underpants
* Step 2: ??
* Step 3: Profit!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.
Good point about mentioning why it exists!
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.
Great article though!
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.
https://github.com/LittleGreenViper/LGV_TZ_Lookup#what-probl...
https://github.com/RiftValleySoftware/RVS_Spinner#what-probl...
https://github.com/RiftValleySoftware/RVS_BlueThoth#what-pro...
https://github.com/RiftValleySoftware/RVS_PersistentPrefs#wh...
https://github.com/LittleGreenViper/LGV_MeetingServer#what-p...
etc.
(clickable link!)
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/
Ask HN: What are some good Readmes you have found?
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
So you download a folder or a zip file (anyone remember PKZIP?) and try to determine what its purpose or "application" is. I mean, there is almost certainly an app in here, right?
So, why have I downloaded this .zip file? Not sure, had an interesting title, and yeah, let's see what the author has to say. First stop: README.txt
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).
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
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?
That being said, I do think its helpful, and I like the fact that other projects' READMEs are noted as good examples too.
Personally I don't like too many images in a README. It's not a SHOWME. That's for your product page.
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.
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.
https://github.com/hbcondo/revenut-web#-workflow
But that diagram just renders as code for the same readme via GitHub Pages:
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.comI'd argue in favor of those. A competent text editor (let's say no older than 40 years old) can highlight and/or render that. When using base markdown, those things add structure to the document. I'd much rather see a markdown file with basics like headers and code sections (which are usually highlighted correctly) than a raw .txt file.
however I think your argument goes doubly hard when dealing with these more advanced html integrated readmes. The md file of the example readme is not well readable when opened in a text file to me- and there's actually very little content there! I prefer a more minimal approach where opening the .md file gives me the information I need, and opening it in a rendered environment gets me some niceties (perhaps you've got badges with coverage or versions nrs idk). But it should work in both.
But I'm not EDITING them. I just want to double-click on it and read the document, rendered properly. I do not want to have to open it in an editing environment and then invoke a preview (which often takes double the screen space). Again, WTF is up with the lack of lightweight, dedicated Markdown viewers?
I don't agree that stuff like ## and `` all over the place is eye-catching and attractive formatting. It's absurdly regressive. At that point, why not just use RTF, for which there are built-in viewers in the dominant OSes? Or if you really want plain text, use indentation, spacing, and capitals to organize the document.
If OSes' default viewers (like Notepad in Windows or Preview on the Mac) would render Markdown, I'd be fine with it. But they don't, and if they haven't added it yet, it doesn't seem that they will.