Ask HN: How to improve technical writing skills? | Hacker News Reader

Ask HN: How to improve technical writing skills?

10 pointsCiPHPerCoder5 comments

I'm nearly always involved in some form of writing process; sometimes code, sometimes not.

I've been writing technical blog posts on my company website for the past year and a couple of them even made the HN front page. Usually, they get ignored even after several re-submission attempts, so I just give up.

When I ask my peers (who are mostly fellow cryptography/security geeks) for feedback, they almost always respond with phrase and/or a quick fix, e.g. "Hey, you messed a sentence up 70% down the page."

If you're interested in what I've written: https://paragonie.com/blog/all

Specific concerns:

* I'm worried that my headlines are too boring to catch anyone's attention. I've always erred against clickbait titles even if the content delivers, mostly because I find them annoying.

* Are there not enough graphical aids? Should I spend more time learning how to use Photoshop?

* Are there any resources you know about for improving the quality of the writing past the headline?

No one else has responded, so I'd like to contribute something, as you're clearly investing time in this.

Technical writing is often cold, fact-based writing. There is the need to be 100% correct and caveat explicitly where necessary.

Technical articles also should assume to require a user's attention, and popular articles deliver a quick fix.

Promoting the use-case for a product isn't technical writing, it's marketing, providing clearly linked outcomes to causes/problems/opportunities that an audience should be aware of (should be).

I had a quick look at your blog, for example 'Solve All Your Cryptography Problems in 3 Easy Steps' * The title is popularist, implying a quick-fix for readers that need a quick thirst-quench. Not that business, as it isn't quantified. A bit like a 20 second page-view blog post. * The content is not. It is long and quite detailed. But now I'm thinking, so who's the audience? If the audience is 'business' write to them with appropriate diagrams and do link to much more highly technical implementation and justification - using external references can help a lot here. * If the audience is implementers, stroke the technical side. How it is not hard, exotic or difficult, but is interesting, well supported, and could also gain some credit if they used the material to bring a business case themselves.

Improve the quality of the writing: Split your audience into buckets of people with different needs, and address those needs.

About learning Photoshop: Forget that. If you want more diagrams, do them in PowerPoint, export as a PDF, then export from Acrobat as an image. Absolute zero learning curve.

This is more general writing advice, but you won't go far wrong by following George Orwell's rules:

:: Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.

:: Never use a long word where a short one will do.

:: If it is possible to cut a word out, always cut it out.

:: Never use the passive where you can use the active.

:: Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.

:: Break any of these rules sooner than say anything outright barbarous.

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).

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.

Corilla looks very promising. Any plans to allow publishing outside of the Corilla platform? For me, it's one of my must-haves.

Thanks 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.

Reply on news.ycombinator.com