Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

I'd like to review your README

liw.fi

Post reply on HN
Print view View original

61–70 of 94 posts

Re: I'd like to review your README

#61

Post by daptaq »

yboris wrote: post #56

If the repository is of an application, I strongly recommend people include a screenshot of it. It blows my mind when someone has spent hundreds of hours to make something that they'd like others to use, and didn't spend the 5 minutes needed to increase its use by (my estimate) at least 5%.

The issue here is that it is meaningless when viewed locally. GitHub made the mistake of turning "README", a file you'd usually read when you download some code into a website format. A README is broken if lines aren't broken, it is full of badges or nonsense like a table of contents (as OP says, a README is not a manual).

Re: I'd like to review your README

#62

Post by SuperCuber »

noxer wrote: post #34

I wish people would find a way to include any code present in a README in some kind of automated test. Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated Maybe not include any code is the better solution, instead add an example folder.

I do something similar: my README contains the output of --help, and I have a CI step that ensures that all the lines of the actual help output are present in the README. Caught me a couple times forgetting to update new flags and version changes.

Re: I'd like to review your README

#63

Post by ehershey »

noxer wrote: post #34

I wish people would find a way to include any code present in a README in some kind of automated test. Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated Maybe not include any code is the better solution, instead add an example folder.

This is brilliant!

It’s one of those things that’s so easy to forget or not even think about but once you see it or think about it, it’s essential.

Re: I'd like to review your README

#64

Post by kevin_thibedeau »

noxer wrote: post #34

I wish people would find a way to include any code present in a README in some kind of automated test. Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated Maybe not include any code is the better solution, instead add an example folder.

Generate it with an m4 include.

Re: I'd like to review your README

#65

Post by pizzapill »

slhck wrote: post #50
nooyurrsdey wrote: post #48

Earlier quoted context omitted.

prism.js the code syntax highlighter is notoriously bad at this. At first I felt bad for being confused by something so simple. But all their code examples for highlighting refer to their own code and you're right, at the exact moment you're trying to absorb new information it is infuriating to deal with the "meta" examples. I don't use them out of that alone.

This is my main issue with Rspec documentation.

RSpec has none of that, a typical example from the first page of their documentation:

  RSpec.describe Widget do
    example do
      expect(described_class).to equal(Widget)
    end
  end
Pretty non-meta.

Re: I'd like to review your README

#66

Post by erikerikson »

nooyurrsdey wrote: post #49
DandyDev wrote: post #12

Earlier quoted context omitted.

To be fair, I think we're talking about READMEs for technical projects here, probably hosted on Github/Gitlab/... And in that context your example is totally clear to me: it's a framework for running (background) jobs asynchronously (i.e. code that does not need to run on the main thread of your program and block) and you can use it both on the server and the browser (so probably JS/TS) and it's not intended to be fe…

Sure the individual words make sense but there's a cognitive load of deciphering that when you're first trying to learn something. A "plain english" no nonsense definition goes a long way to introduce your concept. Save the fancy technical jargon for further down in the README if you must.

You have a point and I might reprioritize.

Specialized terminology allows the communication of complex concepts compactly. For the specialists a brief description like you mentioned is perfect. If you give it first, that person can read it and decide.

It should certainly be followed by a tear down or other plain English explanation of what the thing is.

Kind of like: ``` Brief

A little longer

Be descriptive about the thing

Go into every detail you want to discuss about the thing in the repository... ```

The jargon fooled blurb makes a great "a little longer" and gets out of the way to let the more readable description be given. Burying that can be a pain.

Re: I'd like to review your README

#68

Post by asutekku »

daptaq wrote: post #61
yboris wrote: post #56

If the repository is of an application, I strongly recommend people include a screenshot of it. It blows my mind when someone has spent hundreds of hours to make something that they'd like others to use, and didn't spend the 5 minutes needed to increase its use by (my estimate) at least 5%.

The issue here is that it is meaningless when viewed locally. GitHub made the mistake of turning "README", a file you'd usually read when you download some code into a website format. A README is broken if lines aren't broken, it is full of badges or nonsense like a table of contents (as OP says, a README is not a manual).

To be fair, i haven’t read a local readme in years. Markdown in github is hands down miles better and provides more value than any local readme openable with any kind of computer could provide.

Re: I'd like to review your README

#69

Post by Rompect »

Omin wrote: post #51
Gadiguibou wrote: post #46

Earlier quoted context omitted.

That's included in Rust![1] Code examples from the documentation automatically become "documentation tests" to make sure your examples are still up to date when updating your code. [1] https://doc.rust-lang.org/rustdoc/documentation-tests.html

The README.md isn't part of the rust code, so it's not checked by this unless you use tools to generate your README from doc comments like https://github.com/livioribeiro/cargo-readme .

Actually, it's possible and even frequently used, for example in lazy-static, through the `doc_comment` crate.

    #[cfg(doctest)]
    #[macro_use]
    extern crate doc_comment;
    
    #[cfg(doctest)]
    doctest!("../README.md");
Now, the readme examples are tested like everything else.

https://github.com/rust-lang-nursery/lazy-static.rs/blob/mas...

Re: I'd like to review your README

#70

Post by mikepurvis »

johnchristopher wrote: post #38
rendaw wrote: post #32

Earlier quoted context omitted.

I'd expect a fast json parser to be harder to use than an easy-to-use or simple one. But if I need to eke out maximum performance on something I'm going to skip the ones that don't have fast in the description - it means the project's goals aren't aligned with my use case. If it's a web project then I'm going to focus on parsers that have have actually considered security over the ones that haven't. These are all imp…

Fast is not a KPI though. It can and is often labeled on anything, making the term useless even when fast is a criteria over ease of us. Maybe something at the top along the lines of : what it does, how and then what are the implications.

Claiming "fast" implies that performance is a project goal, possibly even tracked over time as a metric, and that there's probably a comparison deeper in the README or elsewhere. It probably also means that when it comes to tradeoffs (compile time, code size, binary size, ergonomics, maybe even strictness/correctness), runtime speed is the preferred option.
Post reply on HN