|
|
|
|
|
|
by dosshell
1624 days ago
|
|
|
>> And even that information is empty bromides about how it's "designed with practicality and efficiency in mind". Hmm, I prefer my software to be impractical and inefficient... the opposite from practical is general. for example is std not practical but general. Its api is not optimized for 95% of the use cases but rather so that everything is possible and equaly verbose. the opposite of efficient can for example be trade of for readability, portability and cost (as in development time). For me as a possible user of the lib i found this information critical. I write always similar info in the readme for my libraries. |
|
|
No, it's certainly not at all. Those are completely unrelated spectrums. Something can easily be practical and general, or impractical and specific.
> the opposite of efficient can for example be trade off for [...]
And if they stated what trade-offs they made, then that paragraph would actually start to say something useful. Unfortunately, they don't.
Also, if you're developing documentation for libraries, I really would recommend finding a better source of inspiration. Take Redis, in the very first paragraph:
> What this means is that Redis provides access to mutable data structures via a set of commands, which are sent using a server-client model with TCP sockets and a simple protocol. So different processes can query and modify the same data structures in a shared way.
That's all you need to do: before anything else, tell the user what the thing does. Then you can give some basic details about implementation: "written in Go", "runs on Linux & macOS", "uses GC, so not suitable for RT applications", etc. After that you can get into trade-offs, real narrow implementation details, setup, handwaving abstract adjectives, etc. But lead with what the hell it actually does.