Hacker News Reader

Comment by aasasd | Hacker News Reader

As I discovered in practice, it seems to be a trend with authors of such small-size software to also forgo any kind of documentation: what options are supported by specific commands, what behaviours they exhibit (which sometimes differs between GNU and BSD). The ‘usage’ messages are also terse and cryptic to the max. Doubly baffling when the audience of the software is supposedly corporations building their userspace. Do the authors sell the docs on the side, or what?

Anyway, for users trying to do stuff with these utils, the available paths seem to be either finding StackOverflow answers from others who already messed with their own systems and survived, or being the first to do the trial-and-error.

View on HN

this is what I think powershell has contributed. you literally can't make a utility that doesn't have documentation because it's generated from the code.

It appears that each command is documented at the top of its respective source file. Though I may be misunderstanding and you mean that that documentation is insufficient.

Regardless, I agree that there should be a proper man page with more detail.

Its been said that the best documentation is source code. For UNIX I have always found this is solid advice. Whats nice about small programs, such as this one, is that its more feasible to use the source code as documentation.

"Anyway, for users ..."

Ah, thats me. I am a user. I personally love terse and cryptic, i.e., minimising the number of keys I have to press. IME, multicall binaries like the OP presume some pre-existing knowledge of how to use the utilities they contain. It seems nonsensical to complain about missing documentation given the purpose of a multicall binary is to conserve space.

With BSD, the utilities in crunched binaries are generally the same ones, i.e., use the same source code, as in one in the userland. With GNU busybox, they are not, and one needs to read the source code to understand the differences.

Even if I can figure out how to use a program from reading documentation I still look at the source code before using it for the first time.

I understand where you are coming from, but just because a program is small does not mean it does not need documentation.

My `bc` is in toybox, but I have put extensive effort into documenting it. [1] I have even documented it for future maintainers. [2]

[1]: https://git.yzena.com/gavin/bc/src/branch/master/manuals/bc/...

[2]: https://git.yzena.com/gavin/bc/src/branch/master/manuals/dev...

I keep wondering what it is that makes C programmers especially antisocial and obnoxious. Is it like in that joke:

Father calls his small son to him, pours a shot of vodka and tells him to drink it. The son drinks, then makes a face and says in repulse: “Eurgh, it's disgusting!”

The man replies: “Yeah, you probably thought your dad drinks honey, did you?”

Individuals who prefer legible, honest signalling and understanding to doing double-work for ignorant, ungrateful people. Yeah, it's a mystery.

In short: "Programs are meant to be read by humans, and only incidentally for computers to execute."

That quotes simply means that you shouldn't write spaghetti code, and that another _programmer_ should be able to read it.

Quite clearly, it doesn't carry a meaning of: "hey, every user now has to become a proficient reader of whatever languages this software is written in."

Ah yes, the famed clarity and readability of C, where people are so entrenched in the belief that the compiler limits identifiers to seven characters or whatever, and in the aversion to typing out a single word in full, that they still build whole new languages with module, function and variable names looking like alphabet vomit. And with ungoogleable (ironically) language names to top it off.

I exclude man pages when I create systems with crunched binaries where I want to save space. The man pages are always available online. Its like djb's programs. They just refer the user to his website. I am not a programmer. I am the user. The small systems I create are for me and no one else, so naturally I make them according to personal preferences.

> Its been said that the best documentation is source code

fuck you. it's a myth perpetrated by lazy programmers, who can't be bothered to spend an hour or two writing a comprehensible usage manual, while otherwise EVERY USER IS GUARANTEED to spend MORE just figuring out how to BEGIN using his crap. It's only forgivable for the simplest of self-explanatory /API/ calls, but /nothing/ in userspace.

Posting like this will get you banned here, so please don't do that.

If you wouldn't mind reviewing https://news.ycombinator.com/newsguidelines.html and taking the intended spirit of the site more to heart, we'd be grateful. In particular, we don't want flamewars, and you've unfortunately already posted quite a few flamewar comments. Can you stick to thoughtful, curious comments instead? That's the kind of conversation we're trying for here. Note that that includes being respectful to whomever you're talking with, regardless of how wrong they are or you feel they are.

I think your comment can be improved by removing your first two words, which brings nothing to this conversation.

Somehow I agree with both parent and you. Ah, life is never black and white...

It's too often that developers adopt this attitude that I have to resort to vulgarity. They are practically forcing my hand there.

The "my actions are THEIR fault" excuse only works in The Manchurian Candidate.

Edit out the expletive and replace the caps with ~ before and after and I'll agree with everything else in the comment.

what a tiresome bore you sound

Please don't cross into personal attack or name-calling, regardless of how bad another comment is or you feel it is.

https://news.ycombinator.com/newsguidelines.html

Documentation != user guide or manual. Manual are part of the documentation. And it is still true that the source code is the best documentation, ideally the source code can be used to automatically generate the docs. But overall documentation and things like ADR will hardly ever find their way into the source so require writing then externally.

> Documentation != user guide or manual

It is within this comment section:

> forgo any kind of documentation: what options are supported by specific commands, what behaviours they exhibit

I too am unskilled at navigating unfamiliar codebases and demand clifnotes because my time as a user is more valuable than yours as a programmer. these gift horses are AWFUL

Reply on news.ycombinator.com