Hacker News Reader

Comment by Panzerschrek | Hacker News Reader

Could you explain please, what is exactly wrong with the README and maybe suggest, how to fix it?

Whenever you are publishing something, whether it be an app, a programming language, ... the examples or screenshots must come first. The reality is that unless you have made a very compelling case beforehand (like with a well crafted screenshot or example), most people will not read your list or description below. Put the examples at the start of the README, they're the selling point of your language not the list of features

For instance, this was the first ever version of the rust-lang.org website:

https://web.archive.org/web/20111226082307/https://rust-lang...

I remember reading it 14 years ago and it was pretty effective at captivating users towards the language. Notice its terseness and the example at the bottom: a reader will first look at the example, then the bullet points above if they're interested, and then the rest of the docs

i like the rust page example…

  use std;
  import std::io;

  fn main() {
    for i in [1, 2, 3] {
      io::println(#fmt("hello %d\n", i));
    }
  }

here’s what the Raku site should look like:

  say “hello $_” for ^3

There two main things:

- Overly boastful language. Nothing is perfect, everything has limitations, etc, etc. If the creator isn't willing to admit that and be open about it then that just means users will hit those issue instead.

- Saying what others are not versus saying what you are. You're talking more about other languages than your own language. Vendors do that as a cheap marketing trick to use the popularity of others to boost themselves.

Reply on news.ycombinator.com