3 ms·
This is a great question, and one that I love seeing emerge with surprising regularity in our dev community. A few thoughts below. For context, I was a technic
by ddri 10y ago
This is a great question, and one that I love seeing emerge with surprising regularity in our dev community.
A few thoughts below. For context, I was a technical writer at Red Hat before spinning out the content tool I cofounded. I'm the cofounder of Corilla, a publishing tool for technical writers... Corilla is like Github for content teams (http://www.corilla.com http://www.corilla.com).
Peer review
When asking for peer review, you will mostly get people pointing out a few minor things and moving on. Doing in-depth reviews are really hard, so it's just human nature to find a few things to comment on and fulfil that emotional contract.
Building up a small circle of very close collaborators for peer review is very helpful. But it's hard work - for example I'm in Boston this week, and I made sure I did a deep-dive on a new content deck sent over from another founder from our NUMA accelerator alumni in Paris. Pay that ^&$& forward first.
Technical writing versus marketing
A long time ago in a galaxy far, far away, technical writers openly mocked sales and marketing. Then something called "Google" happened, and writers that didn't take the time to appreciate that every page is now page one suddenly found their career prospects shrinking.
Technical writing is a very specific art, but one that is broadening widely. I look at "technical writer" in the same way as "full stack engineer". The oldskool days of learning dry and emotionless technical writing were kind of like an engineer getting down with LAMP. Ditto how IA and HCI has blossomed into UX.
The best technical writers understand the power of their content and how it intersects with the needs of the reader. And some of those readers are making purchasing decisions. So you can either argue about "technical writing has become content marketing", or you can learn as much as possible to improve your ability to write the right content for the right persona at the right time. Right?
Clickbait titles
Personally I hate them and avoid content because of them. Unless I encounter them because of a trusted referral in my network. Or if the body content is enough to drive my user journey towards that content.
Your case will depend on your target demographic. Are they inclined for clickbait titles? Are they mostly referred by trusted sources/social media? Are they driven by google (or, lol, Bing)?
Graphical aids
I worked with a manager once that was proud that they never watched videos and hated graphics. That was a great experience, because much of the universe is the opposite.
I can list off a lot of figures that support the conversion/retention/activation power of these other forms of content, but it's 2016. We don't have to. It's not even a debate anymore.
The challenge is that they ALL work. Most of us grew up reading MAN pages, right? So what? A good technical writer has to and loves to test the content preferences of their users.
I wouldn't suggest you learn Photoshop necessarily. You could use Freelancer/Upwork to get some expertise in. If you want to DIY, get a design buddy (or pay a few bucks on Upwork to get taught) how to use Sketch and Marvel/InVision. The design space is shifting quickly.
Get better at technical writing?
Join the Write The Docs community. Seriously. Eric is probably reading this thread right now (g'day!), and they are just a wonderful global community of diverse technical writers. The WTD conferences are super sweet too.
Hope that helps. Ping me directly anytime, I live in this space and love to help.
- strongai 10y agoCorilla looks very promising. Any plans to allow publishing outside of the Corilla platform? For me, it's one of my must-haves.
- ddri 10y agoThanks for your feedback, and absolutely. We're in beta now and the HTML output (going to S3) was useful for validation of the workflow. We're working on the output formats and API at present - a lot of our beta users like Corilla as a kind of technical writing IDE, which is very interesting. If you have any specific output requests/formats, drop me a line anytime.