Hacker News new | ask | show | jobs
by babyeater9000 978 days ago
I feel like git should have a standardized howto.md or something that gives you some version of instructions on how to use the software in this repo. Especially in a case like this where there's no context as to what this thing needs to be used for how it's useful why I should use it what the advantages might be etc.
2 comments
diggan 978 days ago
Disagree :) Having a `examples/` or `demo/` directory is already good enough, and this repository even has one of those too! https://github.com/aperturerobotics/bifrost/tree/master/exam...

One of the examples seems relatively easy to grasp if you're a web developer, about how to do HTTP forwarding: https://github.com/aperturerobotics/bifrost/blob/master/exam...

link
babyeater9000 978 days ago
I'm not a web developer. None of this is intuitive or easy to grasp for me. Even the inclusion of the demo and example directories weren't easy for me to find because they aren't standardized. The fsf also thinks that free documentation is important. https://www.gnu.org/philosophy/free-doc.html . I view software like this as pretty exclusionary. We will have to agree to disagree, but I would say that the amount of people with requisite experience to understand software is lower than the amount of people who are (or in my particular case, were) interested in learning about it by looking through the source. This interaction is a prime example of why the free software movement stalls. Software written by insiders, for insiders is exclusionary from my point of view.
link
diggan 978 days ago
> Software written by insiders, for insiders is exclusionary from my point of view.

Where do you draw the line? At one point, you have to accept that some projects require deep and context-specific knowledge. I can't be expected to be handheld if I dive deep into some math libraries without knowing the prerequisites. And if I do anyway, it's up to me to figure out at least the basics on my own.

The README has the examples and explanations you're looking for, they're just using the language common in the peer-to-peer ecosystem, as it's a peer-to-peer library/cli/daemon.

link
themoonisachees 978 days ago
...which is kind of what is being complained about by GP. I'm not going to pretend that anyone who can actually read this readme has enough expertise in p2p networking to remake bifrost (obviously it's quite a thing, if it does what it says it does) but at a glance it certainly feels that way.
link
ReactiveJelly 978 days ago
That should just be in the README.

Like my ideal readme is:

- 1 screenshot, even if it's a CLI app or web server or something

- 2 sentence elevator pitch

- pip install / cargo install line

- Command line examples

link