4 ms·
What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is,
by commandlinefan 7y ago
What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this information because there are no problems that this thing actually solves…
- LeonB 7y agoAgree. Comparisons (head to head) are a different category again. And hard to find (apart from as partisan sales pitches). Particularly useful if you know X and wondering if/why to consider Y. I often look at “alternativeto.net” to find products/services because we often choose things based on similarity and points of difference with things we already know.
- uhoh-itsmaciek 7y agoAnd how it's worse! It's extremely rare, but some projects do tell you, "If you need X, consider Project Y instead."
- roelschroeven 7y agoWebpages of many many projects do this very badly. I mostly resort to reading the corresponding wikipedia articles, if any, which often are clearer about what the project does and how it relates/compares to other projects.
- commandlinefan 7y ago> Webpages I've had hit or miss success even when I drop $50 on an O'Reilly book on the topic.
- Crinus 7y agoI'd generalize this with a "why". Why does this project exist? Why does that functionality exist? Why does it uses those types? etc (though you could say that this is part of the "Explanation" quadrant)