Comment by dcow | Hacker News Reader

Comment by dcow | Hacker News Reader

Parent Full thread

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

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?

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?

> riddled with ## and other junk

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

"A competent text editor (let's say no older than 40 years old) can highlight and/or render that"

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.

My point is the ## provide structure and for me help to visually lay out the document, so I like reading markdown. To each their own.

Reply on news.ycombinator.com