A Dictionary for Documentation People

Whether you're new to technical writing, a seasoned pro moving to a new role, or just someone who likes to make sure they know their stuff, there are a lot of terms, tools and methodologies for documentation people to get their head around.  Below is a list of things which are common in our industry, with a short explanation and links for further reading.  It's not an exhaustive list, so if something's missing leave a comment and I'll add it in.

Agile

Agile "is an umbrella term for a set of methods and practices based on the values and principles expressed in the Agile Manifesto."  An agile methodology is primarily one which focuses on self-organising, multi-functional teams (that is, teams where every member can do more than one job), a prioritised to-do list in which the priorities can be reordered in response to external changes (e.g. stakeholder feedback, shifting business priorities, etc) and an iterative approach to development that delivers small parts of the whole over time.  Agile methodologies have their roots in Lean manufacturing and arose in direct response to the formally prevailing Waterfall methodology, also known as "big bang delivery".  In practise, Agile is often a synonym for Scrum, which is by far the most used and most familiar agile methodology.  However, there are other agile methodologies, such as XP (eXtreme Programming), Disciplined agile delivery (DAD), Kanban and many other.  See also: Kanban, Scrum, Waterfall

API

An API (Application Programming Interface) is a set of functions that can be used to interact with an application.  In modern software development, with its emphasis on web technologies, Infrastructure/Platform/Software-as-a-Service and Cloud hosting, it's very common to encounter web APIs, but there are also large numbers of API suites for operating systems, client applications and software frameworks.   API documentation is a specialist skill that requires knowledge of the code the API was written in, as well as scripting and markup languages like JavaScript and/or XML.  There are tools such as DapperDox and Swagger that help developers and writers create API content and if you move into API documentation you'll almost certainly use these or similar tools.  See also: DapperDox, Swagger/OpenAPI

AsciiDoc

AsciiDoc is a free, open source Help Authoring Tool that allows you to write in plain text and convert it to HTML, XHTML and DocBook formats (there are open source tools to convert the DocBook format to PDF, Epub and other formats).  It is lightweight, configurable and has a strong user community, and is maintained, updated and documented by Stuart Rackham, the original author of the programme.  Of course, such benefits come with a cost: AsciiDocs is designed on and primarily for Linux, so although there is a port to Windows it is still command line heavy and will come as a bit of a shock if you're used to a slick GUI as your primary interface. Nonetheless, it's a popular choice, especially amongst writers with a technical background, and its command line nature means it works well if you want to add a level of automation to your document build process See also: Help Authoring Tools, Markup, Plain Text

Confluence

Confluence is an enterprise wiki used for documentation, knowledge management, and collaboration.  It is part of the Atlassian suite of enterprise productivity software that includes Jira.  See also: Content Management Systems, Jira, Knowledge Management, Wiki

Content

Content is specifically the part of written output that is concerned with delivering meaning.  Whereas formatting is concerned with how the output is displayed, content is concerned with what the output contains. Technical writers generally write in a Help Authoring Tool that divorces the content from the formatting, or in plain text which can then be imported into some form of HAT to apply the formatting in the output.  Content can also mean, more generally, the output itself.  This is the context in which "content" is used in content marketing and Content Management Systems, which are concerned with, respectively, using output to help drive sales, and storing, sharing and managing output.  See also: Content Marketing, Content Management Systems, Formatting, Help Authoring Tools, Plain text, Technical Writer
 

Content Design

Content design is the process of designing and creating content based on user needs.  This sounds like a fancy term for a standard technical writer responsibility - we write for our users already, surely? - but it's the heavy focus on the user need rather than the product that marks content design as something different from previous approaches.  Content design either started with, or was championed from very early stages by, GDS (Government Digital Service) and in particular Sarah Richards, the (now former) Head of Content Design at GDS.  Her book is the standard tome on the subject and reflects the GDS mantra of designing for user needs in whatever field, not just content.  As with Content Strategy, this is something that will not go away and isn't a buzzword, which is why more and more technical communication roles refer to Content Design as a function, or name the role as a Content Designer.  If you're struggling to find roles called "Technical Writer", they're still there but they're probably called "Content Designer" instead.  See also: Content, Content Strategy

Content Management

Content Management is the creation, publishing and maintenance of content, primarily written documents and multimedia such as graphics and video. Where Information Management is concerned with the regulation of information as a corporate asset (retention, permissions), and Knowledge Management is concerned with making that information available to the right people at the right time (searching, sharing), Content Management is concerned with the actual information itself (writing, maintaining).  Content Manager may be a specific role, although it is often part of the responsibility of a Technical Writing/Documentation Manager who will make content management part of the standard day-to-day activities of their team of writers.  Content Management Systems (CMS) are used to store, share and publish content to the appropriate audiences, and Content Managers normally have (at least) some responsibility for managing these tools.

In the sense that Content Strategy deals with the overarching questions about the goals of the content, Content Management is concerned with the tactics of achieving that strategy by writing the content that the strategy demands and publishing it appropriately.  This includes designing the content to make sure it meets the users needs, something which is critical if the content is to meet the Content Strategy aim of "useful, useable content".  See also: Content, Content Design, Content Management Systems, Content Strategy, EDRMS, Information Management, Knowledge Management

Content Management Systems

Content Management Systems (CMS) are applications that are used to store, share and publish content to an audience.  Normally they are designed to display content through a browser, either on an intranet or website.  Unlike an Electronic Document and Records Management System (EDRMS), a CMS is not (generally) a document storage application, although the boundaries are blurry and it's a rare enterprise-level CMS that doesn't allow attachments to be added to pages.  But the key difference is that a CMS will have pages showing content, whilst an EDRMS will have folders or libraries of documents.  Wikipedia is probably the most well-known CMS (even if most users have never heard of a content management system) but there are many others around, such as WordPress and Confluence.  See also: Confluence, Content, Content Management, EDRMS, Information Management, Wik 

Content Marketing

Content Marketing tries to pretend that what used to be known as "advertising" is actually "content".  When thinking of "content marketing", remember that it is "marketing", plain and simple.  There's nothing wrong with marketing per se, but it's nothing to do with content design, content strategy or technical communication, as these things are based on helping users, not convincing them to buy stuff.  Your content can help keep existing customers and encourage new customers, but that's a by-product of good documentation and not the core function.  If content is helping people use your product, content marketing is trying to persuade them to buy your product. 

Content Strategy

Content strategy "plans for the creation, publication, and governance of useful, usable content."  This quote is taken from the seminal article on the subject by Kristina Halvorson, an article which I should probably just quote verbatim rather than trying to put my own spin on it. (Alternatively, you could just buy her book.)  Content strategy seems to be one of those things which has gained traction in the content community and isn't going away.  Because it's a philosophy, attitude and approach, rather than a specific tool or technology, and because it's self-evidently useful as we build our cathedral of knowledge about how to "do" content, it really is worth spending some time diving into content strategy.  Jobs that mention content strategy experience or specifically Content Strategists are becoming more common and this is unlikely to change any time soon. So read the article, and then look at this massive list of content strategy resources to continue your learning.  See also: Content, Content Design, Content Management
 

DapperDox

DapperDox is an open-source API documentation tool that allows you to overlay rich content authored in GitHub-flavoured markdown onto Swagger/OpenAPI specifications.  As with AsciiDocs and Jekyll it is command line heavy and designed on, and primarily designed for, Linux/UNIX but it can also be run on a Windows machine.  DapperDox was written by Chris Smith, noted ZX Spectrum electronics expert, software architect and API designer (caveat: I know Chris and have presented with him on API documentation).  See also: AsciiDocs, API, GitHub, Jekyll, Swagger/OpenAPI

Diacritics

A diacritic is a symbol or glyph added to a letter, primarily to show how that letter is to be pronounced in the context of the word. English is one of the few languages that has virtually no diacritical marks outside of ones borrowed along with a word from another language, such as naiveté from French.  You can find out more about diacritics and how to add them in various help authoring tools here.  See also: Help Authoring Tools, Grammar

DITA

DITA (Darwin Information Typing Architecture) is an open source XML data model for designing and publishing written content.  It's a form of structured content that employs topic-based authoring and metadata for content reuse and conditional processing (adding topics to different outputs automatically based on metadata).  DITA has an extensive user community that provides much information and guidance and there are a myriad resources for everyone from complete beginners to experienced professionals looking to take DITA further.  See also: Content, Formatting, Markup, Single Sourcing
 

EDRMS

EDRMS (Electronic Document and Records Management System) is the rather clunky name for the modern equivalent of a filing cabinet.  Unlike a Content Management System, the primary role of an EDRMS is not to display content but to store it.  An EDRMS will at minimum allow granular permissions over who can view and edit the documents, and provide automated retention functionality that deletes or archives documents after a certain time period.  The aim of an EDRMS is to provide a secure, accessible space over the whole document life cycle.  The best known EDRMS is probably SharePoint, Microsoft's widely-used enterprise application that can also act as a Content Management System (as both intranet and external facing website), but there are a host of other providers.  See also: Content Management Systems, Information Management, Knowledge Management
 

Flare

MadCap Flare is a Help Authoring Tool for content development.  Created by a large chunk of the team that used to work on Adobe's RoboHelp, it's rapidly become the strongest contender for the crown of most fully-featured and popular HAT.  Unlike tools such as AsciiDocs, Flare has a complete GUI and lots of features and functionality that turns writing and publishing into a workflow rather than stand-alone tasks.  Madcap provide certifications both for students and trainers, and there are a plethora of in-person and online training courses available, as well as the annual MadWorld conference and a healthy online community of users.  There are also multiple additional MadCap products that help manage the entire document life cycle.  In short, Flare and its associated family of products are the 800-lb gorilla of the tech writing world, so there's a good chance you'll use it if you have a long and/or varied career as a writer.  See also: AsciiDocs, FrameMaker, Help Authoring Tools

Formatting

Formatting is the part of written output that is concerned with how the content is displayed.  This covers things like font choice and size, emphasis (bolding, italics), and location of text on the page.  Help authoring tools divorce formatting from content so that the writer can concentrate on the content.  The formatting is dealt with at the level of the output, which means content can be single sourced into different outputs without requiring changes by the writer.  See also: Content, Help Authoring Tools, Single sourcing

FrameMaker

Adobe FrameMaker is a Help Authoring Tool designed primarily for writing long documents like books or manuals.  Whilst some consider it as a direct competitor to Flare, the use cases are slightly different.  Flare is more of an all-rounder, but its focus on single sourcing multiple outputs makes it ideal for topic based authoring and quick deployment.  FrameMaker is a more specialised tool (although it too has all-round capabilities) that makes it ideal for building large and complex documents.  This means that FrameMaker use skews towards industries that need large, complex, highly-structured documents with a long life cycle, such as rail engineering, or publishing companies that don't have much of a need for topic reuse, chunking or publishing on Content Management Systems. Adobe prefer to sponsor conferences rather than run them, and there are no official certifications for FrameMaker, but there is still a vibrant user community and plenty of in-person and online training courses (I recommend CherryLeaf if you're in the UK).  See also: Flare, Help Authoring Tools

Git

Git is a free and open source distributed version control system that is immensely popular amongst developers.  It holds code in repositories (or "repos") and tracks every change ever made to the files in each repo. Whilst the Git website claims that Git is "easy to learn", and they provide comprehensive documentation, Git is still a developer tool that can only be fully used via the command line.  It has a notoriously high learning curve, especially for non-developers, to the extent that jokes about the complexity of doing things such as a merge or a rebase are common even amongst the developer community.  That being said, Git can and is used for non-development work, not least of all documentation, and there are GUI clients that will allow you to do a significant subset of things that you can do on the command line, although some commands are only available through the command line.  This cheat sheet of Git commands might help you here. There are plenty of training options for Git, such as Try Git, and other example such as here, here, and here, and more advanced training like Learn Git Branching and Oh Shit, Git! Like many of the items in this glossary Git has a very active user community, so Google is your friend if you're looking for help, training or tutorials.  See also: GitHub

GitHub

GitHub is a web-based repo hosting system for Git, so that users don't need to host their own repos.   It also provides access control, the ability to request features, bug tracking and various other functionality built on top of Git.  As with Git, there are many online resources to help you learn GitHub, and realistically learning Git without learning GitHub is a bit like learning to be a mechanic without ever learning to drive.  Some example tutorials are here, here, and here, but there are plenty of others.  GitHub is also the birthplace of GitHub Flavoured Markdown, which due to the popularity of Git/GitHub is a widely used markdown variant.  See also: Git, Markdown

Grammar

Grammar is the set of rules that determines the structure of a language.  It includes such things as syntax, morphology, phonetics, and semantics.  Very roughly, these can be treated as sentence rules (syntax), word rules (morphology), sound rules (phonology) and meaning (semantics). The skill of a writer is concerned primarily with semantics (the message being conveyed in natural language), whereas the skill of a developer is concerned primarily with syntax (the correct logical construction to yield the intended result in a programming language) See also: Natural language, Programming language, Semantics, Syntax

Help Authoring Tools

A Help Authoring Tool, also known as a HAT, is a program that technical communicators use to generate their output.  The primary benefits of a HAT include, but are not limited to, the divorce of content from formatting, the ability to single source different output types (HTML, CHM, PDF etc) from the same content, auto-generation of TOCs and glossarys, and versioning.  See also: AsciiDoc, Flare, FrameMaker

Information Management

Information Management (IM) is concerned with what, how and when information should be retained and distributed as well as how long it should be retained for.  Unlike content management it is not primarily concerned with creating or maintaining information, only the management of it once it enters the system.  IM is heavily process and policy driven, normally using an EDRMS, and treats information as a corporate asset to be identified and catalogued.  There is some overlap with Knowledge Management, but the two functions are distinct as IM is normally responsible for meeting legal and regulatory requirements for record keeping and knowledge management is not.  See also: Content Management, Content Management System, EDRMS, Knowledge Management

ISTC

The ISTC (Institute of Scientific and Technical Communicators) is the world's oldest professional body for people who write documentation.  It hosts an annual conference called TCUK which attracts many of the biggest hitters in the UK industry.  If you're a technical communicator in the UK then the ISTC is your professional body, and it's dedicated to helping its members develop as professionals by sharing knowledge, skills and opportunities. See also: STC, WriteTheDocs

Jekyll

Jekyll is a static website generator that allows you to take plain text and turn it into a website.  It is a Ruby/Python application built on and primarily run on Linux, although there is a unofficial Windows port.  As with AsciiDocs, Jekyll is command line heavy, which makes it ideal for automating builds, but also gives it a high learning curve if you're used to GUI interfaces.  There are lots of tutorials available such as easy guides to setting up a simple website and video tutorials but be warned that to use Jekyll you'll need to have a good grasp of website deployment, Linux and coding principles.  See also: AsciiDocs, Plain text

Jira

Jira is an issue tracking application used by development and project teams to track their work.  Originally it was a simple bug tracking application, but over the years it has metamorphosed into a fully-featured workflow management and reporting tool, primarily designed for teams working in agile sprints.  It is part of the Atlassian suite of enterprise productivity software that includes Confluence.  See also: Agile, Confluence

Kanban

Kanban is an agile methodology that takes a production line approach to developing software.  Unlike Scrum, which uses repeating iterations of time (also called sprints), Kanban uses continuous flow to move whatever is the highest priority job through a pipeline until the job is completed.  The best-known element of Kanban is the Kanban Board which displays tasks in columns based on their place in the pipeline.  These columns can be as simple as To-Do, In Progress and Done, although you can use as many columns as there are steps in your process.  Kanban boards are used in Scrum, and are popularly used in task tracking software such as Jira and Trello.  See also: Agile, JIRA, Scrum

Knowledge Management

Knowledge Management (KM) is concerned with the collection and use of information within an organisation.  Unlike Information Management, which focuses on the legal and regulatory requirements for record keeping, KM is primarily concerned with the effective and efficient use of information within the business to improve outcomes.  This means preventing data silos, making tacit knowledge explicit, knowledge transfer, especially from a single point of failure (that one person/team who are the only ones who know about a certain business critical thing), providing new and better ways to easily collaborate, and building a culture where things are written down in publicly accessible places.  Documentation/technical writing is sometimes considered a subset of KM.  See also: Information Management, Technical Writing

Lorem Ipsum

Lorem Ipsum is filler text that is used as a proxy for the content when designing the formatting of a document.  Originally this was used in physical typesetting so that printers could produce demonstration pages before a writer had provided the content; this had the added benefit that they would be ready to print as soon as the content was provided.  Nowadays lorem ipsum is used primarily in electronic content formatting for websites, PDFs, and other content.  Word can produce lorem ipsum text for you and you can specify the number of paragraphs and lines per paragraph that you want.  There are a number of lorem ipsum generators if you don't want to use the traditional quasi-Latin text but be warned that some of them contain NSFW language.  Bacon Ipsum is of course highly recommended.  See also: Content, Formatting, Word

Markdown

Markdown is a markup language that uses extremely simple tags.  It is designed to allow people to write documents in plain text, which can then be converted into well-formed HTML or XHTML.  There are a number of variants of Markdown, most of which extend the original syntax to include things like tables, and well-known variants include GitHub Flavoured Markdown and Markdown Extra.  See also: Git/GitHub, Markup, Plain text
 

Markup

A markup language uses tags to annotate text so that readers (such as web browsers) can parse the tags and add formatting.  The best-known examples of markup languages are HTML and XML, but there are many others.  The W3 consortium maintains complete tutorials for HTML and XML, alongside other common and standardised languages used in web development. See also: Content, Formatting, Markdown

Natural language

Natural languages are languages that have evolved or grown organically without premeditated planning or structure, such as English or German.  The term "natural" is used to differentiate between "normal" human languages and artificial languages that have been designed specifically for a purpose, such as a programming language.  The primary functional difference between a natural language and a programming language is that programming languages have tightly controlled syntax and semantics.  This means that even a small error in the syntax renders the programme unintelligible to the computer running it, and the meaning of the terms in the language - the semantic content - is static, context independent and universal (every element of the language means the same thing in every programme as each element can only be treated one way by the computer).  Natural languages have syntax rules as well, otherwise no-one could communicate with each other, but there is more flexibility and redundancy in these rules.  The semantic content of a natural language is dynamic, context dependent and localised (dialects, for example).  Technical writers use their skill in natural language semantics to communicate a message, whereas developers use their skill in programming language syntax to tell a computer to perform an operation.  See also: Grammar, Programming language, Semantics, Syntax

Plain text

Plain text is text completely divorced from formatting.  At its most basic, this means ASCII or Unicode encoded characters with no specific requirement for font, font size, colour, or formatting like line breaks or emphasis. The practical reality of plain text, seen best in a .txt file opened by a programme like NotePad, NotePad++ or vi, is that line breaks and tab spaces are normally encoded in plain text as well.  As long as the programme rendering the text can deal with ASCII or Unicode (which it almost certainly will be able to do, as these are the prominent global character encoding standards) then text that is divorced from formatting is largely platform-agnostic.  This has many advantages, not least that the writer can specify how something should be formatted - e.g. with emphasis - and leave it to the programme consuming the text to format it.  This allows single-sourcing, where a piece of content can be displayed in different formats without having to be changed, as the rendering programme will deal with the format.  See also: Content, Formatting, Single Sourcing

Programming language

A programming language is an artificial language used to provide instructions for a computer, usually as a sequence of operations to be performed under certain conditions.  They are differentiated from natural languages such as English or German, which have evolved or grown organically without being designed.  Programming languages have syntax (the rules governing the correct usage of the elements of a language) and semantics (the meaning of the elements of a language), but unlike natural language both of these things are tightly prescribed.  Developers are much more concerned with the syntax of a language, whereas technical writers are much more concerned with the semantics.  This is because the skill of the developer is in passing instructions to the computer to make it perform the desired operations, whereas the skill of a writer is in communicating information and understanding to a reader.  See also: Grammar, Semantics, Syntax, Natural languages,

Scrum

Scrum is an agile methodology that uses iterations (also known as sprints) to produce a working product piece by piece.  This is in marked contrast to the "big bang delivery" of traditional Waterfall projects.  Scrum is comfortably the most used agile methodology with 58% of respondents to the 11th annual State of Agile report from 2017 using Scrum as their methodology of choice and a further 10% using a Scrum/XP hybrid.  Due to this popularity and 2 well-known Scrum bodies (Scrum.org and Scrum Alliance) there are plenty of forums, communities and trainers around to help you learn Scrum.  Both Scrum bodies offer certifications and resources to help you master the methodology.  When you see a job application that requires experience of agile methodologies, then if it doesn't specify a particular methodology you can be fairly sure it means Scrum.  See also: Agile, Kanban, Waterfall

SDK

An SDK (Software Development Kit) is a "collection of software used for developing applications for a specific device or operating system".  These collections often require extensive technical documentation to allow a user to become familiar with the tools, frameworks and environments.  This normally includes code samples written in the appropriate language and other highly technical information, so technical writers who can write SDK documentation are highly sought after (and normally well-paid).  See also: API, Programming language

Semantics

Semantics is a subset of grammar and deals with the meaning of words and sentences.  Natural languages can have extremely complex and/or ambiguous semantic contexts, whereas programming languages have semantics which are always very precisely defined.  See also: Grammar, Syntax, Natural languages, Programming languages

Simplified Technical English

Simplified Technical English (STE) is a language standard originally created for the aviation industry, although it can be used in other industries as well.  STE is an example of a "controlled language", that is, a language which limits what users can say and how they can say it.  The aim is to provide a standard that guarantees that non-native English speakers at a certain basic level of competency will be able to understand what's been written.  Contrary to popular belief, only around 3% of the words in STE relate to the aviation industry; it is the simple sentence structure and removal of ambiguity like synonyms and metaphors that makes STE so useful, especially in international companies or industries.  There are plenty of STE resources such as this, a Google+ forum, and even a plugin for Flare to validate your STE.  See also: Flare

Single Sourcing

Single sourcing is an example of the "Create once, use many" philosophy. It is also known as content reuse and is analogous in concept to code reuse, in that you can change the source code/documentation, compile your project and create a new deliverable with that change made everywhere the content is reused.  Markup languages like HTML and XML allow the divorce of content and presentation. The essence of single sourcing is to write the content once and then use markup to present it in different ways.  This can be in a different format - PDF, CHM, HTML, printed, etc - or in the same format but with different content "chunks". Large, homogeneous documents such as entire help files don't lend themselves to single sourcing, unless identical copies are going to be created in different formats (e.g. a PDF and a printed format).  Therefore single sourcing requires a topic based authoring approach, where individual topics can be reused in different outputs and in different formats.  It is for this purpose that DITA and its structured topic approach were designed. See also: Content, DITA, HTML, Markup, XML

Slack

Slack is a chat application that allows users to post in group channels or by direct message to individuals.  It is not a documentation-specific tool but is mentioned here because its use is so ubiquitous within (especially) software development circles.  If you've never used Slack before then you can create your own Slack work space for free and have a play around with it, which is recommended if you are planning on joining a company that uses it.  Slack has become the default communication tool in many workplaces, far outstripping email in volume of messages passed (at the time of writing I am the owner of a Slack instance and an O365 global admin for my organisation and the stats say that the dev teams on Slack send virtually no email in comparison to their Slack usage), so get used to using it.

STC

The STC (Society for Technical Communication) is a professional society for American technical communicators.  It claims to be the oldest such organisation in the world, despite it being created 5 years after the ISTC (1953 vs 1948).  However, being British we don't like to make a fuss, and we know how important these things are to our American cousins, so we're happy to let them keep fooling themselves.  After all, kids, eh? What can you do?  Anyway, if you're a North American, this brash upstart is your professional body and they're very active, with an annual conference and multiple regional conferences throughout the year.  See also: ISTC, WriteTheDocs

Swagger/OpenAPI

The OpenAPI specification (formerly known as the Swagger Specification) is a definition format to describe RESTful APIs.  Commonly described as a "Swagger spec", an OpenAPI specification of an API provides users with an explanation and description of the elements of an API without requiring the user to read the actual code.  The specification can also be used to auto-generate code and documentation using various tools that have been developed.  Tom Johnson has written an excellent tutorial for Swagger, alongside his highly-regarded API documentation tutorials, but there are plenty of resources online to learn about Swagger/OpenAPI.  See also: API, DapperDox

Syntax

Syntax is a subset of grammar, for which it is often confused.  Whilst grammar deals with language as a whole, syntax is concerned primarily with the structure of sentences and how words should be ordered within them (i.e. the grammar above the word level).  See also: Grammar, Semantics

Technical Communication

Technical communication is the communication of technical concepts and/or instructions on how to do something.  The term covers a broad church that includes technical writing, technical illustration/drawing, content strategy and content design, as well as referring to specialist tools and techniques that technical communicators use.  See also: Content Design, Content Strategy, Technical Writer/Author

Technical Writer/Author

A technical writer is someone who creates and maintains technical documentation about how things work.  This may be in the form of manuals, help files, FAQs, guides, tutorials, release notes, installation notes, explanations, descriptions, specifications, SDKs docs, or any other form of documentation that transfers knowledge to others.  In modern technical communication a writer may also produce video material, spoken material and presentations.  Normally the writer is expected to use various applications such as help authoring tools, version control and content management systems, as well as understand methodologies such as Scrum, Kanban and other agile methodologies.  See also: Every single item in this glossary

Version Control

Version control is the management of information, primarily permissions, versioning, branching and merging.  Documentation and software development are traditionally heavy users of version control (or source control for software, from "source code").  Common practise now is to use a Distributed Version Control System (DVCS), where every user has a complete repository held locally, rather than the older centralised systems where people worked on a single centrally located repository.  This has led to a rise in branching (where users create a separate, unique version of one or more parts of the repository) and merging (merging the branches back in to the master version), which requires a more complex tool set than previous version control systems needed.  Whilst many content management systems and EDRMS applications provide permissions and versioning, it is the branching and merging that truly sets a DVCS apart when using one for documentation.  Popular DVCS applications include Git/GitHub, Microsoft's Team Foundation Server (TFS) and Subversion, although there are plenty of others.  See also: Content Management Systems, EDRMS, Git/GitHub

Waterfall

Waterfall is a project management methodology that was predominant until the advent of Agile.  Unlike Agile methodologies, which develop in an iterative fashion to provide incremental elements of a solution over time, Waterfall is a linear process which delivers everything in one go, hence why it's often called "big bang delivery".  Traditionally, a software project being run using Waterfall will complete (something like) the following steps, in order: Analysis, Design, Build, Test, Deploy, Maintain.  Each step must be complete before starting the next step.  The arguments about which is the better methodology to use are legion, but there's no doubt that Scrum is far more popular in software houses.  Productivity tools like Jira and Trello are designed for Agile environments and it's a rare software house nowadays that asks for Waterfall experience rather than Agile experience, although that doesn't mean that it's easy to get Agile right and not end up with each sprint being a mini-Waterfall.  See also: Agile, Jira

Wiki

A wiki "is a website on which users collaboratively modify content and structure directly from the web browser. In a typical wiki, text is written using a simplified markup language and often edited with the help of a rich-text editor."  By far the best known wiki is Wikipedia, from where the quoted description is taken, which uses MediaWiki although there are many different wiki providers.  Wikis are popular as knowledge management hubs because users can edit the pages themselves, unlike a traditional website or intranet, and technical writers are often responsible for updating their organisation/department's wiki. See also: Confluence, Knowledge Management

Word

Word is a word processing application for writing documents.  It's the writing package that just about everyone who's ever used a computer is familiar with, although professional writers rarely use it for writing documentation (we tend to use specialised Help Authoring Tools).  In the same way that people who don't know much about football - that's soccer, to our American cousins - expect players to be great at keepy-uppy, even though the skill is rarely required in an actual game, people who don't know much about technical communication will expect technical writers to be good with Word.  You can either be one of those rude people that mocks anyone who asks for help, or you can help them and be a, you know, decent human being and good colleague.  If you go with the latter approach then you'll find lots of good training material from Microsoft here.  See also: Help Authoring Tools

WriteTheDocs

WriteTheDocs (WtD) is a community of practise that doesn't have memberships or fellowships or offer certifications.  Instead, its aim is to create, hold and encourage conferences and meetups, both online and in real life, where anyone interested in creating great documentation can learn, teach, network and generally grow their knowledge and understanding of how to create great documentation.  WriteTheDocs has an active Slack instance, a regular podcast, holds a couple of big conferences every year, has active meetup groups in cities around the world and they also have specialist APITheDocs meetups.  If you're looking for a community of like-minded documentarians, WriteTheDocs is for you.  See also: ISTC, STC


If there's something missing from this list, or you've got a link to a useful tutorial, let me know in the comments and I'll add it in (and give you a shoutout to boot).

A List of Style Guides for Writers

Style guides cover a multitude of areas and it can sometimes be difficult to separate the purely writing-focused guides from the general UI/UX guides.  This is not surprising, considering how much UI/UX, technical writing and comms/marketing are starting to coalesce around the central idea of user focused design. But if you're not working in that environment, or if you are but you still want some purely writing focused resources, it can be a little difficult to sort the wheat from the chaff.

With that in mind, I've put together a list of some useful guides below:

Online

• MailChimp - One of my absolute favourites because they focus on the likely user mood at the point of the interaction, and tailor their writing accordingly.  This is a relatively unknown style guide, but it should absolutely be one that you spend time looking through.
• Mozilla - A (relatively) short and to the point style guide that focuses on developer documentation.  If you write for developers (SDK, API, etc) then this is an excellent resource.
• Apple - As you would expect from Apple, this is not the longest style guide but it is proscriptive.  One of the most useful features is the table that converts "developer speak" to "user speak", so for example "focus ring" for an Apple developer is Highlighted area" or "area ready to accept user input" for an Apple user.
• Google - This focuses on writing for a worldwide audience and as such is concerned with clarity and simplicity above all.  If you're writing for a geographically diverse audience, especially one which is not highly technical, then this guide will help you a lot.
• GDS - The Government Digital Service guidelines for the UK Civil Service.  Not as easy to navigate as many guides, because topics are provided in an A-Z format rather than curated into groups, but contains a lot of information and is recommended if you're writing in UK-English. (The lack of curation is odd; GDS people are normally very big on user-focused design, and this...isn't.  But if you can get past that, the information contained is often difficult to find elsewhere.)  
• 18f.gov - The American equivalent of the GDS style-guide, this is focused more on US-English and the needs of federal/state public bodies, as you would expect.  But it's comprehensive, well-written and very good on grammar and "correct" writing so even if you're not writing in US-English, it's still a very useful resource.  And if you ARE writing in US-English, it's indispensable.
• Microsoft - Microsoft provide one of the best known and popular style guides in print (see below) but this resource is far too valuable to miss off the list.  The link takes you to a page with just a single dropdown, from which you can download a PDF style and language guide for just about every language you've ever heard of, and many you haven't.  French, German and Russian are fairly obvious, but how about Khmer, Igbo and Xhosa (the African language with the clicks)?  If you write in any language other than English then this is probably the single most valuable guide on this list.

Print

• The Elements of Style - The classic book on how to write.  The focus is not on software documentation (unsurprisingly, as it was first published in 1920), but not having a copy of this is like being a quantum physicist who's never read Einstein's papers on relativity.  Some things are just fundamental to your profession.
• The Economist Style Guide - Another without a software focus, and the first edition was published 30+ years ago, but if you want to write clearly and - according to the Economist - with a little flair, this is the book for you.  Its best feature is undoubtedly its effort to focus on real-world examples that are universal in application without being generic to the point of mere common sense.
• The Chicago Manual of Style -  If you've only heard of 1 style guide, the chances are it's this one.  Now on it's 16th edition, it includes specialised sections on writing for digital technologies, including writing with XML.  If your office doesn't have this on its bookshelf, it should be because you've got the next guide on our list.
• Microsoft Manual of Style - A slightly more specialised guide than Chicago, but no less useful for it (and probably more so if you're a technical writer).  Unless you write software for Apple and only Apple, this guide will show you why so much software documentation has the style and tone that it does.
• The IBM Style Guide - One of the most comprehensive style guides available for the modern technical writer.  It is particularly strong on Information Architecture and content design, but don't let that fool you: this is a standout resource for all writers.
• Developing Quality Technical Information - Another IBM publication and not strictly a guide, but so useful that leaving it off the list for that reason would be petty.  There is significant overlap with the IBM Style Guide, but this focuses more on training you and less on being a reference work.  Unless you're an acknowledged expert in technical documentation, you'll gain a great deal from this book.

There are lots more style guides out there. If you have a favourite that's not in the list then tell me in the comments and I'll add it in.

Are Technical Writers Becoming Obsolete?

When I started working in the software industry just after the turn of the century, there were Technical Writers, Document Authors and occasionally - just to spice things up a bit - Technical Authors.  All 3 of these roles did the same thing: write end user documentation that would either be printed or displayed on screen in a help format like CHM.  This documentation was aimed either at people who installed, configured and administered the software, or at users who had to navigate the UI on a daily basis to do their job.

Nowadays, every part of that has changed.  We have Information Architects, Knowledge Engineers, Content Strategists, UX Writers and "Document Wranglers" (no, me neither).  All of these roles seem to do different things, and none of them seem to have writing good old-fashioned help documentation as their primary role.  End user documentation seems to have become very passée, with little love left for a large body of writing that explains how something works. The notion of putting documentation into a .chm is scoffed at; the notion of providing a printed copy is as old-fashioned as the idea of burning your DevOps maven because she might be a witch.

Some of these changes are driven by technology.  With many applications being solely or largely online, it makes no sense to provide a .chm when a .chm is essentially just HTML, CSS and JavaScript.  There's a better, faster, more open delivery mechanism for that, and it's called a web page. On that note, as dial-up has gone the way of the phone box, there's no need to send customers the help file on a CD or on actual paper through the post.  People can download a 500 page 10mb document in a couple of seconds, although the irony is that as the documentation is delivered online using topic-based authoring, they can pick and choose what they want to see so they'd never need the whole documentation stack anyway. 

Likewise, the explosion of mobile apps and the sudden realisation that yes, good UX design IS ACTUALLY IMPORTANT (a fact that many, many companies seem to have been oblivious to pre-smart phone) has meant that a lot of small companies are letting their design do the communication for them, and the absolute minimal documentation required is in the form of prompts, labels and warnings.  These are done, if anyone does them formally, by the UX designer or a dev who's more interested or more junior than the other devs.  The mobile apps created by big companies have also forced them to realise the importance and value of good UX design, but unfortunately the completely expected has then happened: "Ooh, we didn't need a technical writer for our new mobile app because of the great design.  Let's apply that principle to our enterprise application and we can save on writers!" (This is despite the fact that their 20-million-lines-of-code enterprise application is lugging around years of technical debt and is so poorly designed that the idea of making it lightweight enough to go online is a running joke amongst the devs.  But sure, get rid of your writers, that's the problem you need to solve.)

And some of these changes have come about because it's now easier to automate some of the writer's job.  If you set up Swagger with the right templates and show a little care, your API documentation, or at least the core of it, can be provided at the press of a button.  Provide your Confluence users with well-thought out templates with mandatory fields and macros linked to JIRA, and your release documentation can be written by anyone in your team.  I would never say that these thing are enough (and I'll believe that to my dying day) but the cost-benefit ratio of hiring a dedicated writer changes with each new automation technology that chips away at the periphery of what the writer does.

However, some of these changes to the writer function are driven by methodology.  In an agile world - and if you're not agile you're very out-of-step with modernity, no matter what you think about it - the specialist is a dying and unwanted breed. No-one can be "just" a writer any more, because what we do often doesn't exist in any meaningful way now. Sure, there are plenty of massive enterprise level applications out there that need equally massive help files, but these are becoming the exception rather than the rule.  This is not helped by disruption on a grand scale from start-ups that value doing one thing really well, and a clientele of millennials who are starting to reach an age where they an have an input into buying decisions, and who are not bothered in the slightest by the idea of buying 10 different apps and using IFTTT to fit them together, rather than spending 20x as much on a behemoth from a 50 years old blue chip. 

With everyone moving to agile, the expectation is that the specialist writer can no longer be siloed into "just" writing documentation.  Hence a role like Knowledge Engineer, where you conduct the fragmentary topics to the right place to form a coherent orchestra for your audience, or Content Strategist, where you act as a lode stone to keep all of the disparate documents from different experts pointing in the same direction.  In many cases it is no longer enough to be able to write; you must be able to plan, build, guide, persuade, manage.  Writing in and of itself is almost secondary.

If you look at the coalescing of the following trends:

• Mobile apps;
• Better UX investment;
• More documentation automation tools;
• Fragmented market of smaller providers;
• Move to "specialised generalists" in agile.
  

Then you'll see that none of them are positive for the working prospects of a "pure" technical writer. It may seem that the pure skill of a technical writer - writing - is less valued than it was before, but the companies that valued this before will still value it now.  It's the changing of the technologies and methodologies that are allowing companies that never really valued documentation to do away with technical writers, and new companies that join the fray don't see the cost-benefit ratio of having a technical writer in the first place.  They hire a Content Strategist to provide a guiding strategy and write some templates, add documentation (using Swagger and other tools) to the Definition of Done, and have a Knowledge Manager to look after the internal wiki and provide light editing of the docs.  They release updates several times a week so there's plenty of scope to iteratively improve the docs as they go.  And that's it.  Where does the technical writer fit into that?  Answer: They don't.  


So where do you go if you're a technical writer?  Do you transition to analysis, QA, testing, product management, training, support, or move to a different industry altogether?  Do you keep chasing the ever-decreasing number of "pure" technical writing jobs?  Do you specialise in API and/or SDK documentation on the basis that it's one of the few areas where there aren't enough qualified writers to fill the all the vacancies?  All of these are valid and sensible options.  In the long run though, you're best off learning how to do all of the things that have been chipped away.  Learn how to use Swagger and other documentation automation tools.  Learn how text is displayed in your application and become its writer, editor and proofreader.  Learn at least the basics of UX design and join the discussions about how best to show - rather than tell - the user what to do next (because no-one is better than you at understanding that).  Become a moderator for forums that discuss your company and its products.  Learn how to manage the knowledge assets your company has.  Learn what a content strategy is and create one.  

Because being a Technical Writer is no longer enough in a lot of companies.  Eventually it won't be enough in any company. 

Write the Docs NA 2016

Sarah Maddox has recently been at Write the Docs NA 2016, and as usual she's posted a series of informative articles about the sessions she attended.  If you're not already following her blog - and you should be if you're at all serious about being a better technical writer - here's the list of relevant posts:

• API Documentation Tools 
• A readable README file
• Values of effective tech writing teams
• Internal docs for startups
• Interactive document environments
• From tech writing to information experience team
• Write the Docs NA 2016 wrapup

I can't stress enough how much useful information Sarah manages to pack into a blog post, so get reading, get learning, get better at what you do.
 
 

The Basics - How to Document APIs

An occasional series looking at best practice for common documentation tasks and situations. 


This blog is written for several purposes. Some of the articles are the amalgamation of my experiences that I'd like to pass on to anyone who is interested, and some are articles that help me clarify and explain my thoughts on certain topics within the realm of Agile Technical Writing.  These cover the majority of the posts here on www.agiledocumentation.co.uk.

But occasionally, I use this blog as an auto-didactic tool when I'm learning about something new.  It helps me to organise and manage the new information and connections; as the old saw goes, "if you want to learn something, try teaching someone else".  The subject of documenting APIs is a case in point.

API documentation may or may not come under the heading of "The Basics", depending on what area you write about.  My background is software documentation, so being able to grasp the basics of API documentation is a requirement for me.  In fairness, the basics are easy to pick up, because the principles are the same for all technical documentation (concision, clarity, accuracy, correct audience target) and the practise is uncomplicated (access, inputs, outputs, effects). However, my experience has primarily been with SOAP web service APIs, which is only one of a number of types of web service APIs, which in turn are only one of a number of types of API.  So I decided to brush up on some of the API documentation knowledge that I'm missing, and was planning on writing an article covering the basics that I learnt.

Normally, the process of learning starts with Wikipedia (because its technical articles are normally pretty accurate on the basics and it often has a useful list of links for further research) and moves on to Googling overviews, tutorials, etc.  This process can last anything from a couple of hours to a couple of weeks depending on what I already know, and how complicated the source material is to get my head around.  Then I write about what I've learnt.  Doubtless this is familiar to anyone who writes technical documentation for a living.

However, in the case of API documentation I can't do the subject justice when there is a better resource for my loyal readers, and it's Sarah Maddox's blog.  Sarah is a Technical Writer for Atlassian and, as I've come to realise, a doyen of API documentation.  I'm not too proud to realise that sometimes there is someone who just knows a lot more than me, and communicates it very well, and in this case Sarah is that maven.  Start here for a good overview of API types, and then review her API category for more great articles.

In addition, there's a good article from the Parse blog on this subject, and anyone that uses the phrase "carefully crafted with love" to describe their documentation gets a respectful nod from me.  You can also find some great examples of API documentation here and here.

If in the future I find an arcane area of API documentation that could use some elucidation then I'll apply myself to that task, but otherwise I'll leave API documentation articles to the experts like Sarah.....

The Basics - How to Easily Format Code Snippets

An occasional series looking at best practice for common documentation tasks and situations. 

Writers who document software will invariably have to document a code snippet or two in their careers.  This could range from the occasional line of CSS in a configuration guide every few years, right up to the full-on, nothing-but-code explanations of the full-time API documenter.

I'll be honest, this post isn't for the API specialists, but it is for those who only have to occasionally format a code snippet, or for those who are looking for a better way.  Those writers who document APIs will need to follow proscriptive standards and understand the code in order to provide clear, coherent information to their readers.  Those writers for whom code is something that people who can't write in a natural language write in instead - you know who you are! (and you're very welcome here) - may however find formatting code snippets a little daunting.

(In case you've never formatted code before, it's not as simple as just changing it to COURIER NEW.  Well, it can be that simple, but not if you want to do a proper job.  Code snippets will be read by people who code, so it should look like code.)

Fear not, my friends, for there is a simple way to format code. 

Your immediate option, if you have access to them, is to use the same tools as the developers.  So for formatting SQL you open up a query writer like SQL Server or dbForge Studio for Oracle, drop the SQL into a New Query window, and then copy and paste into your document.  You can do the same with code if you have access to an IDE like Eclipse or Visual Studio.

However, the problem with industrial tools like these is two-fold: Speed and Cost.  Industrial tools are not built to open in half a second 30 times a day; they're designed for heavy duty coding, and that makes them less than rapid at opening.  And although Eclipse is free, Visual Studio, SQL Server and dbForge Studio are not.  As I've discussed elsewhere, people should have the licences they need, and it doesn't seem a good use of your budget to spend large amounts of money on licences just so a writer can format code a bit quicker.

Besides, who wants to have to open a SQL application, and an IDE, and an HTML editor, and an XML editor, and a CSS editor several times a day?  If only there was a lightweight, fast, free, easy to use application that would open these files with the odd extensions automatically and quickly, and just format the code for us!

Well, there is.  It's called Notepad++ and seriously, it's awesome.  

If you're not a particularly technical person, Notepad++ might have passed you by, but it is essentially the Swiss-army knife of coding and it is free, lightweight, very quick, and it will format whatever legitimately extensioned code file you give it with ease.  Well, let me rephrase that: The list of programming language file extensions it supports is very large, and the chances of you working on one that isn't supported by Notepad++ is low.  All you have to do it right-click a file and Open with Notepad++ - or set Notepadd++ to be the default program for opening the code files you need to format - and it'll do the rest.  

Here's an example .xml file opened in standard Notepad:

And exactly the same file in Notepad++:

That is out of the box, default functionality.  I created a new text file, wrote some XML in it, saved it, renamed the file to XML.xml, and opened it in Notepad++.  All you have to do at this point is cut and paste the code into your document, and you're good to go.  

I'll come clean with you on one thing: If you want it to auto-indent code that hasn't already been indented, you will need to install a plugin.  But that's not too tough an ask, especially if you deal with existing, indented code. By default Notepad++ will change the indent of the TAB button to the standard indent for whatever code you're working in, so as long as you haven't got long screeds of unformatted code to work with, indenting it yourself is very easy.  There is also a very active user community, as Notepad++ is used by millions of people around the world, so if you have questions there's a good chance the answer is available already, or someone will answer it for you if you ask on a forum.

If you've got another tool which you think is as good as or maybe even better than Notepad++, please share it in the comments.