Sunday, 1 November 2015

What Are The Different Types of Writer?

Over the years I've lost count of how many times I've had to say "I don't write that kind of documentation" when someone's asked if I can write something for them.  I'm always polite about it, and I'm always willing to write it for them despite my lack of experience in that area, but nonetheless the overwhelming response is one of bemusement that I can't just magic up a document for them.  I mean, it's just writing, and you're a writer, so why can't you, you know..... write it?

Now, I'm not talking about writing where domain knowledge is a problem. That can be an issue, but in a pinch if a developer can explain something to me and I can understand it I can write some documentation if I have to, even if I don't have the domain expertise I normally try to have. No, this is people asking me to write detailed SDK documentation for a product I've never seen in a language I've never been exposed to, or a configuration guide for a technology I've never worked with, or - my particular favourite - sales literature.

*deep breath*

Seriously.  You don't hire a Ruby developer to normalise your database, or hire a mainframe guru to go heavy on JSON.  And these people work in designed, limited languages.  Technical writers operate in an unlimited, organic language in which meaning can be efficiently delivered in any number of ways.  It might come as a surprise to the ignorant (of which, sadly, there are many in the tech industry) but writers specialise just like coders do.  Yes, just like a good coder we can turn our hands to quite a few things, and we're pretty good in the areas around our specialisation, but an API writer is about as far from a marketing copy writer as a compiler programmer is from a mobile app developer. 

With that in mind, here's a quick guide to some of the main types of technical writer:


API/SDK Writers

Not the same thing, because an API is not the same thing as an SDK, but the basic skills are the same: highly technical people, writing for other highly technical people and able to read, parse and write code.  These writers are quite rare, because they need to be proficient in the language(s) you use whilst also being very good writers.  This makes them valuable; expect to pay accordingly.

Technical Product Writers

Known as "Technical Writers" in the same way as End-User Product Writers (see below) but these writers focus on things like Installation, Configuration and Integration.  If API writers are coders who can write, Tech Product Writers are IT engineers who can write. These writers have experience with enterprise systems like Active Directory, IIS/Apache, databases, and all that good structural jazz that applications use but end users never see or need to know much about.

End-User Product Writers

As above, these are just known as "Technical Writers" but rather than focusing on the people who install, configure and maintain the technical infrastructure, they focus on the people who'll actually use the application.  This means writing for different targets, from newbie data entry interns to experienced SysAdmins.  This is probably the "classic" technical writer that people picture when they hear the job title - writers of help files, user manuals, release notes, data dictionaries and so on.

End User Product Writers normally cover the biggest range and will often be the writers who cover "the rest", like knowledge base articles, FAQs, Support documentation, and anything else that is needed on the technical side of the product. Once you get further away from the product than this, you end up with....


Sales Engineering Writer

If the Sun is the product, Mercury and Venus are the API and SDK documentation, and the Earth and Mars are configuration/user guides, Sales Engineering Writing is Pluto.  That is to say, it's right on the outer fringes of what can legitimately be called technical writing.  But that's mainly because these writers work in Sales rather than Dev or Product Management or Support - i.e. places where technical people work - and so there's a certain amount of suspicion about their motives.  But hey, I run a broad church here, so I'm including them.  Sales Engineering Writers take technical concepts and put them into the simplest possible terms for Sales people to use in demos and tenders. In fairness, that's a tough job - have you ever tried to come up with an easily-understandable analogy for a self-balancing AVL tree? - because after a certain level of simplicity documentation changes from "really simplified" to "useless" and that's a fine line.

MarComm

Short for Marketing Communication.  It's close, very close, or identical to a Copy Writer, depending on what company is hiring, but the essential difference is that Marketing Communication is often seen (rightly or wrongly) as being more marketing focused, especially in that social media way that everyone's pretending to love now at big companies, whereas copy writers are seen as more broadly spread over the sales and marketing gamut.  Sadly we've already got as far out as Pluto, so I can't make a Uranus joke.  

Copy Writer

A copy writer is someone who - duh - writes copy. Copy used to mean specifically journalistic writing, but over the years it now means relatively short pieces for public consumption, usually to get a specific message across. (Yes, the irony of saying that I'm not a copy writer as I write a short piece for public consumption to get a message across is not lost on me, but I'm not selling anything so it's not the same thing.) This means writing text that is designed to help pique interest in a product or service and aid sales.  Copy writing and MarComm are firmly in the Sales and Marketing domain, and are about as technical as the salespeople they work with.


Following from this, there are quite a few domain areas that writers specialise in:

  • Software
  • Medical
  • Finance
  • Aerospace
  • Rail
  • Maritime
  • Military (primarily because of the security clearance you need and the specialised writing standards they use)
These can all be broken down further, and I'm sure I've also missed some out (don't be afraid to enlighten me in the comments!), but it is further evidence that "a technical writer" is not a one-size-fits-all solution to your documentation needs.  Each of these domains is specialised enough that they will be advertised as such - "Medical Writer", "Aerospace Writer", "Finance Writer", etc - in the same way that legal jobs are advertised - "Tax Lawyer", "Criminal Lawyer", "Contract Lawyer" etc.  They might all come under the umbrella of "Technical Writer", but their knowledge, skills and experience are very varied.  The only things they have in common are great English skills and an understanding of the principles of technical communication.


This article is by no means exhaustive, but at least you can wave it at the next person that thinks that a writer is a writer is a writer.  And don't be afraid to ask them why they think technical writing is easy enough for people not to have specialities......

No comments:

Post a comment
http://www.agiledocumentation.co.uk/2015/11/what-are-different-types-of-writer.html
www.agiledocumentation.co.uk
crawl=CC-MAIN-2021-17
81610
application/http; msgtype=response
sha1:72HRMA32QQXWDQT3ARBSWL6HEVAWUPE5
<urn:uuid:9c663c46-eab8-4e65-9cff-9d6bc7727bc4>
2021-04-17T05:50:13Z
172.217.13.243
text/html
sha1:ITT32OKSXU7XLSVRBNAAVAVV5C43USMH
<urn:uuid:4e7bfac8-9eb5-42b3-9257-920599cb8309>
http://www.agiledocumentation.co.uk/2015/11/what-are-different-types-of-writer.html
response
<urn:uuid:f8516b29-8142-4cd5-874e-40ebcbd05525>
isPartOf: CC-MAIN-2021-17
publisher: Common Crawl
description: Wide crawl of the web for April 2021
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-37.ec2.internal
software: Apache Nutch 1.18 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.2-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/