Sunday, 22 February 2015

Does a Writer Need to be Able to Read and Write Code?

In a word: Maybe.  In several words, maybe, but it depends on what you mean by "code".  Technically speaking, "code" means a compiled language like C#, Java or C++, whereas "markup" means tagging languages like HTML, SGML or XML and "scripting" means code that can be interpreted, for example by a browser, like JavaScript, Perl or Python.  There is also SQL, which is a language specifically used for querying databases.  Although this comes under the "code" branch of the family tree of languages, I'll be treating it as a separate skill here, for reasons I'll explain later on.  Some of these things a writer must be able to read and write, some they probably should be able to, and some they'll never have to unless they want to.

You Must Be Able to Read and Write Markup

A common requirement for Technical Writers is the ability to at least read, and normally edit, markup.  This is because:

a) The Darwin Information Typing Architecture (DITA) standard is used by many companies, and that is an XML data model, and;

b) Most modern content authoring tools such as MadCap Flare, or document processing tools such as Adobe Framemaker, use markup to structure the content, whilst showing the content to the writer in a WYSIWYG front end. 

Being able to interpret and edit markup is therefore an necessary skill in many, if not most, technical writing jobs.  Cascading style sheets (CSS) are used to define the format of the content; being able to manipulate HTML without being able to manipulate CSS is like being able to draw a picture but not be able to colour it in, so if you can read and edit markup, you'll probably need to read and edit CSS as well.  So in the case of markup (and CSS), the answer to this question is yes, as a Technical Writer you should be able to at least read and interpret HTML, XML and CSS, and preferably edit it as well.

(If this is something you can't do, there are free on-line lessons for HTML, XML and CSS)

You Probably Should be Able to Read and Write SQL

SQL (Structured Query Language, often pronounced "sequel") is the standard language for interrogating relational databases.  There are as many flavours of SQL as there are relational database products but the 3 most widely known are probably Microsoft SQL Server, Oracle and MySQL.  Each of these has a slightly different syntax, but nothing which deviates hugely away from the ANSI standard. Being able to read and write at least basic SQL (in any flavour) will allow you to interrogate a database, amend data and produce SQL code samples if you need to.  The requirement to do these things varies enormously between jobs, but it's a common enough requirement that it's worth learning.  Luckily, the basics of SQL such as retrieving all data from a table where column x = value y, inserting or deleting a row in a table, and finding out the lengths and data types of all the columns in a table are very easy to learn and there are good tutorials available.

There are a lot of different coding languages and frameworks, and which one(s) you'll come across depends very much on the industries and companies you work for, but SQL is used anywhere that relational databases are used.  That makes this skill portable regardless of what coding languages you might need to get to grips with (see below), hence SQL gets its own section here.

You Don't Have to Read and Write Code and Scripts. Unless You Want To.

For code and scripting languages, the situation is different.  If you are creating release documentation for an application, it is a lot less likely that you will need to be able to read, let alone write, code or scripts. Code isn't information rich and it's not the best way to understand the functionality that's been developed (that would involve demonstrations and asking questions). So why would reading code be helpful?  The answer lies in the necessity for developer-to-developer documentation, and this means APIs.

An API (Application Programming Interface) is a set of functions that can be used by programmers to access the operations that are held internally in an application***.  To document them properly, you have to be able to identify the inputs, outputs and upshots, that is, what needs to be passed in, what will be passed back out, and anything else that the API function will do if it's accessed.  And if you want to find that information out, you're going to need to read code and/or scripting languages.  API documentation is a speciality within technical writing and many writers, even if they document software for a living, won't ever have to do it. But it is a very valuable string to your bow because (as of 2015) there is a strong demand for API writers, and with the trend towards the Internet of Everything, the need for API documentation that allows developers to get products talking to each other in a meaningful way is only going to get higher. 


The drawback (for some people) of documenting APIs is the emphasis on the "Technical" part of the "Technical Writer" job title.  A lot of Technical Writers are people who love using the written word to de-mystify the mysterious and elucidate the complex, so they see themselves as writers who specialise in technology, rather than technologists who write.  If you're documenting APIs though, you need to be a technologist AND a writer, because aside from documenting the inputs, outputs and upshots, you'll have to write code samples using the existing code line as a guide.  Someone else's code can be quite opaque to the initiated, never mind the uninitiated, and if there's a lack of rigorous code comments then hoo boy, look out, that's a world of pain right there.  API writers love to work through this pain and produce coherent documentation from it, so if that sounds like you then congratulations, you're in demand! As long as you can read and write the code.




*** - For those of you that have API experience, you're right, it's not quite that simple!  But this will do as a simple explanation for those people who've never met APIs before.