3 ms·

I consider myself pretty decent at writing. I don't love writing but it has always come fairly naturally to me, much easier than it appears to come to most peop

I consider myself pretty decent at writing. I don't love writing but it has always come fairly naturally to me, much easier than it appears to come to most people. Which is surprising, given how absolutely mediocre I am at nearly everything else in life. :) ("Those that can, do. Those that can't... write?") I'm frequently aghast at how utterly _terrible_ most technical documentation is. Even the docs for a lot of prominent enterprise and open source software is just awful to use. What drives me the most insane is dry, passive voice. Passages that descriptive rather than prescriptive ("the widget is a surmounted on a logarithmic casing, widdershins of the two spurving gears"), contain zero diagrams or illustrations of how things are put together, and _definitely_ don't contain anything like a tutorial or getting-started guide. Every once in a while I consider jumping into the field of technical writing just to clean it up a little. But I would probably find it immensely dull after a short period of time.

wheelinsupial 4y ago
I have explored technical writing a little bit. There are actually a fair amount of people that have majored in the humanities or literature of some sort. They complain about how they have to write in a dry, passive voice. If some of them had their way, the documentation would read differently. I don't think anyone in tech writing is trying to put out bad documentation. I've read many complaints about not being given access to the device or software, being left out of license provisioning, being kept out of the loop in sprint planning and other meetings, or being told late in the documentation stage that functionality has changed. If the writers don't have access to blueprints or can't access the software, documentation doesn't get pictures. Some of the devs and engineers respond poorly to requests for screen grabs or doing other administrative work for the tech writers. I don't think there is a simple solution here. What are the incentives and how does tech writing help or harm. In some cases, helping a tech writer is time spent away from development. Or you can blame UX issues on poor documentation to blame the tech writers.

wheelinsupial 4y ago

I have explored technical writing a little bit. There are actually a fair amount of people that have majored in the humanities or literature of some sort. They complain about how they have to write in a dry, passive voice. If some of them had their way, the documentation would read differently. I don't think anyone in tech writing is trying to put out bad documentation. I've read many complaints about not being given access to the device or software, being left out of license provisioning, being kept out of the loop in sprint planning and other meetings, or being told late in the documentation stage that functionality has changed. If the writers don't have access to blueprints or can't access the software, documentation doesn't get pictures. Some of the devs and engineers respond poorly to requests for screen grabs or doing other administrative work for the tech writers. I don't think there is a simple solution here. What are the incentives and how does tech writing help or harm. In some cases, helping a tech writer is time spent away from development. Or you can blame UX issues on poor documentation to blame the tech writers.