How to write a great README • Hacker News Board

Re: How to write a great README

#41

Post by mgbmtl » Tue, Jul 18, 2023, 8:38 PM UTC

avgcorrection wrote: post #16

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

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!

Re: How to write a great README

#42

Post by hbcondo714 » Tue, Jul 18, 2023, 8:49 PM UTC

spacebanana7 wrote: post #14

rlnorthcutt wrote: post #3

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 thos…

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

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

Re: How to write a great README

#43

Post by yboris » Tue, Jul 18, 2023, 8:51 PM UTC

Please include a screenshot if it's ever appropriate. You will save your visitors so much time!

Re: How to write a great README

#44

Post by ShadowBanThis01 » Tue, Jul 18, 2023, 8:52 PM UTC

dcow wrote: post #21

drako999 wrote: post #2

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…

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 acc…

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?

Re: How to write a great README

#45

Post by johanneskanybal » Tue, Jul 18, 2023, 8:57 PM UTC

tl;dr although my first principle is good readme files.

Re: How to write a great README

#46

Post by slily » Tue, Jul 18, 2023, 9:00 PM UTC

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.

Re: How to write a great README

#47

Post by zuckerborgggg » Tue, Jul 18, 2023, 9:41 PM UTC

[flagged]

Re: How to write a great README

#48

Post by dcow » Tue, Jul 18, 2023, 9:58 PM UTC

ShadowBanThis01 wrote: post #44

dcow wrote: post #21

Earlier quoted context omitted.

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 acc…

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, sinc…

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

Re: How to write a great README

#49

Post by ShadowBanThis01 » Tue, Jul 18, 2023, 10:45 PM UTC

dcow wrote: post #48

ShadowBanThis01 wrote: post #44

Earlier quoted context omitted.

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, sinc…

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

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?