For most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.

▲

derf_ 5 days ago | parent [-]

I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places).

And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.

▲

ctkhn 5 days ago | parent | next [-]

Way too much documentation is like this. Then again, lots of times asking coworkers about an existing system or a new ticket that's not detailed properly ends up with them saying 30 pages of fluff to me before I can get to the nugget

▲

bonoboTP 5 days ago | parent | prev [-]

This really is one of those things that AI can improve, and already improves today.

	▲	ctkhn 5 days ago \| parent [-]
		As much as I'm not an AI booster, it has helped a lot when I hit a wall with poorly done documentation where the related bits I need are scattered all over and even a text search isn't helping me