I'd like to review your README • Hacker News Board

Re: I'd like to review your README

#91

Post by naniwaduni » Sun, Apr 18, 2021, 5:21 AM UTC

tmotwu wrote: post #27

nickjj wrote: post #21

Earlier quoted context omitted.

> My pet peeve with README DHH had a funny line around Dropbox's "mission" in his 2019 railsconf video (linked to the direct point in the video): https://youtu.be/VBwWbFpkltg?t=2818 Dropbox's official mission as of 2019 was: "We're here to unleash the world's creative energy by designing a more enlightened way of working" And DHH's remark was: "For fuck's sake Dropbox, you host files and make them appear on all of my…

Customers don’t infer the purpose of a product from it’s company mission. The audience of a company mission are employees themselves. Dropbox has expanded to more than file syncing over the past decade. It makes sense to have a broad vision of their future, e.g purposeful mission. Imagine Amazon telling employees to stick it to books because thats the business they started off with. Like why should AWS even exist, it…

> Customers don’t infer the purpose of a product from it’s company mission. The audience of a company mission are employees themselves.

ok sure then why is it in big red text on a customer-facing page, then?

Re: I'd like to review your README

#92

Post by mongol » Sun, Apr 18, 2021, 7:38 AM UTC

tmotwu wrote: post #27

nickjj wrote: post #21

Earlier quoted context omitted.

> My pet peeve with README DHH had a funny line around Dropbox's "mission" in his 2019 railsconf video (linked to the direct point in the video): https://youtu.be/VBwWbFpkltg?t=2818 Dropbox's official mission as of 2019 was: "We're here to unleash the world's creative energy by designing a more enlightened way of working" And DHH's remark was: "For fuck's sake Dropbox, you host files and make them appear on all of my…

Customers don’t infer the purpose of a product from it’s company mission. The audience of a company mission are employees themselves. Dropbox has expanded to more than file syncing over the past decade. It makes sense to have a broad vision of their future, e.g purposeful mission. Imagine Amazon telling employees to stick it to books because thats the business they started off with. Like why should AWS even exist, it…

It is a very good point. And the mission points to the future, where the management wants the company moving. It should not describe what it does, but where it is heading.

Re: I'd like to review your README

#93

Post by jeddy3 » Sun, Apr 18, 2021, 7:43 AM UTC

mikepurvis wrote: post #70

johnchristopher wrote: post #38

Earlier quoted context omitted.

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.

"[description], aimed at speed" or something like that is better in that case, IMHO.

Re: I'd like to review your README

#94

Post by Liskni_si » Sun, Apr 18, 2021, 10:41 AM UTC

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've been using https://github.com/brodie/cram for this. It's a neat little shell testing tool that can be told to check that every 4-space indented markdown code block output what it says it outputs, so I just cram my README.md.

An example of this in action: https://github.com/liskin/liscopridge/blame/68a656b7beb10a5c..., https://github.com/liskin/liscopridge/blob/68a656b7beb10a5cd...