21–30 of 87 posts
He gives writing tips based in how the mind works. Instead of a bunch of rigid rules, you can understand it based in cognitive theory.
I liked the approach of Pinker's book "A Sense of Style": https://stevenpinker.com/publications/sense-style-thinking-p... He gives writing tips based in how the mind works. Instead of a bunch of rigid rules, you can understand it based in cognitive theory.
https://www.alejandraquetzalli.com/book-designing-developer-...
it might be a little more on the practical "nuts and bolts" side of things vs. "how do i write well", but it covers lots of areas that always seem to come up when producing documentation for developers.
First, without hiring more people, I would advise contacting your closest University and ask about graduate faculty who offer grant writing courses. For a small fee, they can provide training and materials for your staff.
Better, though, would be to target a non-technical grant writer and integrate that person into your team. Any communication for an exterior audience would flow through that person. I say non-technical, because that helps you avoid jargon and other "meaningless" items for exterior audiences. I also say specifically grant writer instead of technical writer because technical writers focus on ensuring all material is included, whereas grant writers also ensure that all material is digestible by human people. This person also learns your organization and can help target professional development for folks who might need it - it's all about creating a talent pipeline.
Source: I am a career grant writer, and any technical writing, especially areas as, for lack of a better word, arcane as tech writing can be vastly improved by succinct grant writers. I have contracted for companies in the past, but so few actually want to make systemic changes; mostly they want quick fixes and immediate solutions.
The best books I've read that helped me with technical writing have been classic writing ones such as Ray Bradbury, Stephen King, Steven Pressfield, William Zinsser, and more.
Also following this general guideline from Orwell may help:
i. Never use a metaphor, simile or other figure of speech which you are used to seeing in print.
ii. Never use a long word where a short one will do.
iii. If it is possible to cut a word out, always cut it out.
iv. Never use the passive where you can use the active.
v. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.
vi. Break any of these rules sooner than say anything outright barbarous.
https://www.orwellfoundation.com/the-orwell-foundation/orwel...
You may also find some gems here and there with big tech companies developer documentation contribution style guides i.e.
https://docs.microsoft.com/en-us/style-guide/welcome/ https://developers.google.com/style
I am a professional technical writer. When I started out, I desperately looked for tips and tricks. Internet was (and is) full of tips but I could not find a tech-writing bibliography. I will soon publish a bibliography of books and guides regarding technical writing. I promise to paste a link here when I am finished, which I believe I will be in a day or two.
I think all technical writing books are dry and boring. The best books I've read that helped me with technical writing have been classic writing ones such as Ray Bradbury, Stephen King, Steven Pressfield, William Zinsser, and more. Also following this general guideline from Orwell may help: i. Never use a metaphor, simile or other figure of speech which you are used to seeing in print. ii. Never use a long word where…