6 ms·

Yeah - I don't actually think I've ever seen that kind of language in technical docs. I don't think this problem exists. Maybe for some very experienced juniors

Yeah - I don't actually think I've ever seen that kind of language in technical docs. I don't think this problem exists. Maybe for some very experienced juniors... but you'd hope they'd get that silliness slapped out of them by more experienced colleagues rather quickly

NateEag 5y ago
I have seen this plenty of times. I can't quantify it, but I saw the title and thought, "GOSH yes. I HATE those kinds of docs."
yourapostasy 5y ago
> ...I don't actually think I've ever seen that kind of language in technical docs. I agree I don't see that in Big Vendor Co. product documentation where Procurement cut a 5+ USD figure check to license it per year (or equivalent subscription). In internal documentation within a company, I see that kind of language all the time. Yet it is the internal documentation that so many of my clients' staff rely upon in their daily operational activities, so while the page count of the internal documentation doesn't match the vendor documentation, the use of that language there hurts my clients a lot more. This leads to a lot of the tribal knowledge-oriented activities I see in most of my clients. The documentation is so disjointed because no one in leadership comprehends how much productivity is lost (because the tribal knowledge papers over the functional loss with unperceived efficiency loss by forcing tightly coupled organizational inter-relationships, reducing organizational agility and capacity to handle complexity) when the documentation provides no pointers between the interstices of detail and scope, or hopelessly mix up the context. It is more of a mixed bag in smaller vendors' software and open source though in aggregate better than internal documentation, and the more successful Big Cloud vendors tend to be relatively better at this. But still far from Apple Macintosh programmer documentation after they opened it up more, IBM mainframe, some sets of inter-related US military field manuals. The most pernicious trend I've seen lately is a level of technical writing that can only be charitably called "symbol manipulation by non-domain familiar writers" who plug and play edits of successive versions of documentation that have been outsourced/offshored to writers incentivized by number of documentation incidents closed than actual coherency across not just the paragraph, but across the page, sections, chapters and books. English as a second language isn't their challenge; within the scope of their limited edits, it is perfectly acceptable; misaligned incentives (often arising from mis-scoped requirements) is the problem.

NateEag 5y ago

I have seen this plenty of times. I can't quantify it, but I saw the title and thought, "GOSH yes. I HATE those kinds of docs."

yourapostasy 5y ago

> ...I don't actually think I've ever seen that kind of language in technical docs. I agree I don't see that in Big Vendor Co. product documentation where Procurement cut a 5+ USD figure check to license it per year (or equivalent subscription). In internal documentation within a company, I see that kind of language all the time. Yet it is the internal documentation that so many of my clients' staff rely upon in their daily operational activities, so while the page count of the internal documentation doesn't match the vendor documentation, the use of that language there hurts my clients a lot more. This leads to a lot of the tribal knowledge-oriented activities I see in most of my clients. The documentation is so disjointed because no one in leadership comprehends how much productivity is lost (because the tribal knowledge papers over the functional loss with unperceived efficiency loss by forcing tightly coupled organizational inter-relationships, reducing organizational agility and capacity to handle complexity) when the documentation provides no pointers between the interstices of detail and scope, or hopelessly mix up the context. It is more of a mixed bag in smaller vendors' software and open source though in aggregate better than internal documentation, and the more successful Big Cloud vendors tend to be relatively better at this. But still far from Apple Macintosh programmer documentation after they opened it up more, IBM mainframe, some sets of inter-related US military field manuals. The most pernicious trend I've seen lately is a level of technical writing that can only be charitably called "symbol manipulation by non-domain familiar writers" who plug and play edits of successive versions of documentation that have been outsourced/offshored to writers incentivized by number of documentation incidents closed than actual coherency across not just the paragraph, but across the page, sections, chapters and books. English as a second language isn't their challenge; within the scope of their limited edits, it is perfectly acceptable; misaligned incentives (often arising from mis-scoped requirements) is the problem.