
Ask HN: How to improve technical writing skills? - CiPHPerCoder
I&#x27;m nearly always involved in some form of writing process; sometimes code, sometimes not.<p>I&#x27;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.<p>When I ask my peers (who are mostly fellow cryptography&#x2F;security geeks) for feedback, they almost always respond with phrase and&#x2F;or a quick fix, e.g. &quot;Hey, you messed a sentence up 70% down the page.&quot;<p>If you&#x27;re interested in what I&#x27;ve written: https:&#x2F;&#x2F;paragonie.com&#x2F;blog&#x2F;all<p>Specific concerns:<p>* I&#x27;m worried that my headlines are too boring to catch anyone&#x27;s attention. I&#x27;ve always erred against clickbait titles <i>even if the content delivers</i>, mostly because I find them annoying.<p>* Are there not enough graphical aids? Should I spend more time learning how to use Photoshop?<p>* Are there any resources you know about for improving the quality of the writing past the headline?
======
zhte415
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.

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

------
ddri
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
Corilla looks very promising. Any plans to allow publishing outside of the
Corilla platform? For me, it's one of my must-haves.

~~~
ddri
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.

