Hacker News new | ask | show | jobs
by wildleaf 2810 days ago
Language inconsistencies within documentation.

Half of all documentation is meant to be read literally. "Follow these exact steps for this exact reason and this exact thing will happen."

Then the other half is written as if you're supposed to have some secret knowledge. "Just run this, do the usual thing people do, and then you'll probably end up with something like this."

Those halves aren't mutually exclusive by document, and it took me a long time to get a feel for what the documentation author's intended.