4 ms·
I find that where there'a magic, there's usually tutorial-style documentation. Not to say there's anything wrong with tutorial-style documentation in and of it
by rl3 10y ago
I find that where there'a magic, there's usually tutorial-style documentation.
Not to say there's anything wrong with tutorial-style documentation in and of itself. However, it becomes problematic when it is the only documentation.
Then you just find yourself digging around in source code because the "It's easy, simple and magic!" style of documentation turned out to be woefully inadequate, if not actively confusing.
- patates 10y agoThis situation keeps occurring especially with tooling. I guess one reason is that the tooling is there to bring in the magic in the first place. The other could be that tools being created because of the needs of a specific workflow and the magic is there because authors just wanted to have something working, then it got popular and now people want to use it in all sorts of workflows.