4 ms·
As someone who spent a long time in technical writing, and wrote a decent-selling book about getting started as a tech writer, here’s my thought: The problems
by jamesgill 1y ago
As someone who spent a long time in technical writing, and wrote a decent-selling book about getting started as a tech writer, here’s my thought:
The problems with software documentation/tutorials/etc. rarely have anything to do with writing skill—because the biggest challenge is not writing, it’s how to analyze and understand the audience and design what ‘documentation’ they need to get the job done. Separate skill(s), unrelated to writing. “Writing”, in fact, is the easy part.
Think of it this way: you can write the most beautiful, elegant, correct JavaScript that’s ever been written: and it can be utterly useless. Beautiful code is good, but that’s not the goal or the focus.
- gmoniava 1y ago[dead]
- jmye 1y agoEven if you believe that writing is the “easy” part, most developers/technical people are still woefully bad at it. I would say that it is, generally, not easy to describe complex things simply, and people who are naturally adept at using language often underestimate the difficulty.
- jamesgill 1y agoI agree, writing is a skill. My point was that when it comes to documentation, other skills are primary. So--I wouldn't advise developers/writers looking to improve documentation to 'become better writers', I'd advise them to focus first on the other other skills, because without them 'good writing' in documentation is worthless. Put another way, the ultimate measure of good documentation is: how well it helps the user accomplish their 'jobs to be done'.