4 ms·
Article is confusing and gives zero actionable advice + a fancy "triangle". In general, after you get to a piece of code you need to have thre questions answer
by catchclose8919 4y ago
Article is confusing and gives zero actionable advice + a fancy "triangle".
In general, after you get to a piece of code you need to have thre questions answered:
- what problem does this solve? - this is actually the problem how-to guides solve, in practice your particular use case is NOT even close to the example use cases, so you'd just read the how-to guides as the no-bs higher level explanations because you know anything higher level is often bs
- how do I get something done with this? - API docs combined with dense explanations combined with dense usage docs (I don't want to have to piece them together myself through my own effort, I want them all in one place)
- what is the reasoning for it being implemented/architected/etc. this way? - design docs + "philosophy" section of docs + architecture diagrams
- Wowfunhappy 4y agoI think the author's point is that code by itself inherently can't fulfill all three sides of the triangle. The cleanest code in the world might make it immediately obvious what a program is doing, but not why it's doing it, or the context in which it's doing it.