3 ms·

Shouldn't the readme first explain what this project is about? How would I know if this is relevant for me/my work. Not trying to be obtuse, I am fairly new to

Shouldn't the readme first explain what this project is about? How would I know if this is relevant for me/my work. Not trying to be obtuse, I am fairly new to CS and I would like to understand what I am looking at and how I could use it in future.

Gualdrapo 2y ago
Can't agree more. After scanning the repo homepage and their website, I still have absolutely no idea what this is supposed to do.
- samtheprogram 2y ago
  It's source code and infrastructure as code for the services that are described at pico.sh, for self-hosting, development, etc. Some of the services appear to live directly within this repo. There's also separate apps (that are separately packaged via docker, and referenced in the docker compose) elsewhere in the same GitHub organization See the docker-compose.yml for an overview of the services that this repo is meant to enable running. Or if you click the link to their site, pico.sh, and hit Getting Started, there's a lot more documentation there.
vietvu 2y ago
The repo is terrible at tell us what is this about, the landing page is better: https://pico.sh https://pico.sh, but still terrible.
kbenson 2y ago
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 2y 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 2y 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 2y 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.
taneq 2y ago
It’s not just you. Looks like a bunch of scripts for web hosting? But I shouldn’t have to click through several layers for the first real clue, and no I don’t want to “Get Started!” with no prior information.
pelasaco 2y ago
it is a bare bones infrastructure as service. It costs $2.
- rkagerer 2y ago
  Could I pay $2.05 and get a one-liner at the top of the readme telling me what I bought?
  - oarsinsync 2y ago
    I think you underestimate the cost involved of creating and supporting something more than barebones. Building a barebones platform for people who are largely self sufficient is cheap. Building a full fat platform for people who need more hand holding, is a bit more costly.
    - xcdzvyn 2y ago
      I have a thing to sell you, it's only $50 and you'll definitely like it; it's great. I won't tell you what it is though - I'm not here to hold your hand.
GoblinSlayer 2y ago
It's for autists.

Gualdrapo 2y ago

Can't agree more. After scanning the repo homepage and their website, I still have absolutely no idea what this is supposed to do.

samtheprogram 2y ago
It's source code and infrastructure as code for the services that are described at pico.sh, for self-hosting, development, etc. Some of the services appear to live directly within this repo. There's also separate apps (that are separately packaged via docker, and referenced in the docker compose) elsewhere in the same GitHub organization See the docker-compose.yml for an overview of the services that this repo is meant to enable running. Or if you click the link to their site, pico.sh, and hit Getting Started, there's a lot more documentation there.

vietvu 2y ago

The repo is terrible at tell us what is this about, the landing page is better: https://pico.sh https://pico.sh, but still terrible.

kbenson 2y ago

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 2y 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 2y 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 2y 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.

taneq 2y ago

It’s not just you. Looks like a bunch of scripts for web hosting? But I shouldn’t have to click through several layers for the first real clue, and no I don’t want to “Get Started!” with no prior information.

pelasaco 2y ago

it is a bare bones infrastructure as service. It costs $2.

rkagerer 2y ago
Could I pay $2.05 and get a one-liner at the top of the readme telling me what I bought?
- oarsinsync 2y ago
  I think you underestimate the cost involved of creating and supporting something more than barebones. Building a barebones platform for people who are largely self sufficient is cheap. Building a full fat platform for people who need more hand holding, is a bit more costly.
  - xcdzvyn 2y ago
    I have a thing to sell you, it's only $50 and you'll definitely like it; it's great. I won't tell you what it is though - I'm not here to hold your hand.

GoblinSlayer 2y ago

It's for autists.