3 ms·

From the top of the readme, it says to look at the docs on the website pico.sh. So, the readme does give info on what it's for by referring you to the authorit

From the top of the readme, it says to look at the docs on the website pico.sh. So, the readme does give info on what it's for by referring you to the authoritative location for that info. Should the source code README explain what it is? Maybe if the github repo was meant to be the main interaction for the project, but it's obvious from following that link that it's not meant to be, given the attention they put into that site. I think what you're actually doing (whether you realize it or not) is criticizing the person who submitted this project's choice to link the github repo instead of the main site, which is a valid criticism, but that isn't really a fault of the project IMO.

voytec 3y ago
> Should the source code README explain what it is? Yes, at least one sentence at the top. Linking to a website containing several "something.sh" titles leading to multiple pages with proper one-sentence descriptions is a silly treasure hunt. I wasn't that interested, gave up after 2 pages and my take is still "they're re-using popular text editor's name, whatever this does".
- kbenson 3y ago
  I'm not sure why you think a single sentence at the top is better than a link to website that documents it, nor why you think it's the job of the source repo to explain what it is instead of how to build it. Sure, in some cases you might want that, but not every source repo is meant to be he onboarding location for people, where they learn what something is and what it's for. It's sort of like expecting assembly instructions to be full of marketing copy about why you want to use the product and why it was made. Presumably, when you're looking at the instruction manual, you're already past that point. Just because someone did the equivalent of handing you an instruction manual does not mean that instruction manual has a major shortcoming by not explaining all the wonderful ways the product it builds can help you. You were given the wrong material without context.
latexr 3y ago
> So, the readme does give info on what it's for by referring you to the authoritative location for that info. Which is also subpar. It’s documentation, sure, but still fails to adequately explain what this is, who it is for, and why should anyone care.

voytec 3y ago

> Should the source code README explain what it is? Yes, at least one sentence at the top. Linking to a website containing several "something.sh" titles leading to multiple pages with proper one-sentence descriptions is a silly treasure hunt. I wasn't that interested, gave up after 2 pages and my take is still "they're re-using popular text editor's name, whatever this does".

kbenson 3y ago
I'm not sure why you think a single sentence at the top is better than a link to website that documents it, nor why you think it's the job of the source repo to explain what it is instead of how to build it. Sure, in some cases you might want that, but not every source repo is meant to be he onboarding location for people, where they learn what something is and what it's for. It's sort of like expecting assembly instructions to be full of marketing copy about why you want to use the product and why it was made. Presumably, when you're looking at the instruction manual, you're already past that point. Just because someone did the equivalent of handing you an instruction manual does not mean that instruction manual has a major shortcoming by not explaining all the wonderful ways the product it builds can help you. You were given the wrong material without context.

latexr 3y ago

> So, the readme does give info on what it's for by referring you to the authoritative location for that info. Which is also subpar. It’s documentation, sure, but still fails to adequately explain what this is, who it is for, and why should anyone care.