4 ms·

So many Open Source repos assume that you already know what the proprietary version is and don't bother to explain what they are, just how they relate to $other

So many Open Source repos assume that you already know what the proprietary version is and don't bother to explain what they are, just how they relate to $other_thing. I got through the whole introduction without any sense for what this was and was hopeful when I saw a Features section that it'd finally explain itself... but no, all I know now is it can download apps (what kind of apps, and to what?), modify buttons to do "any function" (out of what set?), and integrate with discord and weather but not some other things (what does 'to be migrated' mean?). If you're writing a README like this, it's a good idea to remember that there are a bunch of people who may be interested in your tools because they're FOSS but would never have interacted with whatever proprietary thing you're comparing them to. Do us all a favor and give a two-sentence explanation for what you're building on its own terms.

zeroonetwothree 2y ago
I read it for about 3 minutes but I still have no idea what this does.
Etheryte 2y ago
Can't help but feel that you're barking up a somewhat nonexistent tree here. This project is for interfacing with the deprecated Spotify CarThing. If you don't know about it, you're very likely not their target audience, so I think it's pretty fine if you don't get it. If you do know what the CarThing is, the readme intro covers what this project does pretty well. In similar vein, you wouldn't expect a Javascript library readme to start by explaining what Javascript is or what a software library is, but if you didn't know those things, you would feel equally lost.
- treflop 2y ago
  A repo on GitHub linked from HN wouldn’t need to explain JS. But it should explain CarThing. Idk. Even in Jira tickets, I write a short background section to bring everyone up to speed. I like when everyone gets a chance to be on the same page.
  - Etheryte 2y ago
    It's a common misnomer to think HN is just software developers, there's people here from all sorts of varied backgrounds. Similarly, CarThing has had posts about it on HN countless times [0], many users here will know what it is. Complaining about it feels pretty moot, especially when it would've taken less time to look it up than to comment about it. [0] https://hn.algolia.com/?dateRange=all&page=0&prefix=true&query=carthing&sort=byPopularity&type=story https://hn.algolia.com/?dateRange=all&page=0&prefix=true&que...
__jonas 2y ago
The whole intro to the project and history lesson is on the website: https://deskthing.app/about https://deskthing.app/about which I think is completely fine, wouldn't want to have that in a repo README personally
riprod 2y ago
Hi, deskthing developer here. I'mma be completely honest, I had no intentions of this blowing up like it did. The Readme has been in desperate need of a revision and documentation is all but nonexistent. Why? Because I'm just a college student who likes coding and figured I'd take on a fun little project. I'm not a company, an organization, and i have no idea what the crap I'm doing half the time! A formal wiki is in the works and will eventually be implemented and linked to across the ReadMes and websites. Thanks for understanding! Cheers
- throwup238 2y ago
  > and i have no idea what the crap I'm doing half the time! Don’t worry. Neither does anyone else. Everyone just gets better at faking it with time.
- lolinder 2y ago
  No worries at all! I'm more commenting on this as a trend even from people who post Show HNs of their own than asking for specific changes to this project! Do what's fun for you, no more, but definitely polish it up if you're looking for broader uptake.
- sciencesama 2y ago
  Great work man
TylerE 2y ago
Seems kinda like it does about 10% of what a Streamdeck does, minus the physical hardware. Of course, for most of those users having the hardware (16 or 32 key macro board with user-controllable displays behind the (clear) buttons. Basically it looks like a keyboard with LCD keys.

zeroonetwothree 2y ago

I read it for about 3 minutes but I still have no idea what this does.

Etheryte 2y ago

Can't help but feel that you're barking up a somewhat nonexistent tree here. This project is for interfacing with the deprecated Spotify CarThing. If you don't know about it, you're very likely not their target audience, so I think it's pretty fine if you don't get it. If you do know what the CarThing is, the readme intro covers what this project does pretty well. In similar vein, you wouldn't expect a Javascript library readme to start by explaining what Javascript is or what a software library is, but if you didn't know those things, you would feel equally lost.

treflop 2y ago
A repo on GitHub linked from HN wouldn’t need to explain JS. But it should explain CarThing. Idk. Even in Jira tickets, I write a short background section to bring everyone up to speed. I like when everyone gets a chance to be on the same page.
- Etheryte 2y ago
  It's a common misnomer to think HN is just software developers, there's people here from all sorts of varied backgrounds. Similarly, CarThing has had posts about it on HN countless times [0], many users here will know what it is. Complaining about it feels pretty moot, especially when it would've taken less time to look it up than to comment about it. [0] https://hn.algolia.com/?dateRange=all&page=0&prefix=true&query=carthing&sort=byPopularity&type=story https://hn.algolia.com/?dateRange=all&page=0&prefix=true&que...

__jonas 2y ago

The whole intro to the project and history lesson is on the website: https://deskthing.app/about https://deskthing.app/about which I think is completely fine, wouldn't want to have that in a repo README personally

riprod 2y ago

Hi, deskthing developer here. I'mma be completely honest, I had no intentions of this blowing up like it did. The Readme has been in desperate need of a revision and documentation is all but nonexistent. Why? Because I'm just a college student who likes coding and figured I'd take on a fun little project. I'm not a company, an organization, and i have no idea what the crap I'm doing half the time! A formal wiki is in the works and will eventually be implemented and linked to across the ReadMes and websites. Thanks for understanding! Cheers

throwup238 2y ago
> and i have no idea what the crap I'm doing half the time! Don’t worry. Neither does anyone else. Everyone just gets better at faking it with time.
lolinder 2y ago
No worries at all! I'm more commenting on this as a trend even from people who post Show HNs of their own than asking for specific changes to this project! Do what's fun for you, no more, but definitely polish it up if you're looking for broader uptake.
sciencesama 2y ago
Great work man

TylerE 2y ago

Seems kinda like it does about 10% of what a Streamdeck does, minus the physical hardware. Of course, for most of those users having the hardware (16 or 32 key macro board with user-controllable displays behind the (clear) buttons. Basically it looks like a keyboard with LCD keys.