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

Some Notes on Moving Content to Confluence

Confluence is a super-charged wiki from Atlassian, the same company that makes the popular issue tracker, JIRA.  As you'd expect with a normal wiki, its most popular function is as a knowledge base, documentation hub and FAQ location, but due to it's tight links to JIRA (and other Atlassian products) it's also used for showing sprint reports, burn downs, burn ups, work in progress, and lots of other reports using data taken straight from JIRA.

In this post we're going to focus on the traditional wiki usage: documentation and knowledge management, and specifically some do's and don'ts when moving existing documentation and knowledge assets into Confluence.  Some of the points below are specific to Confluence, some are best practise whenever you're moving knowledge from one place to another, but they're all born of experience and hopefully they'll help you avoid some of the pitfalls.

The most important points first:

• If you're a technical person, get a content person in before you move anything.  They'll spot issues you won't. 
• If you're a content person, get a technical person in before you move anything.  They'll spot issues you won't.
  

I'm more of a content person, and having some technical people (i.e. developers) around helps immensely.  A developer's first thought is always "How can I do this through code?", which means they're much better at spotting situations where a batch file or a regex or some CSS will make everything a lot quicker and less manual.  When I was looking at moving documentation from some internal wikis, it was developers who helped me find the appropriate export functionality and worked out whether I could take that format and import it into Confluence, potentially saving me weeks of work.

Which brings me neatly on to:

• Automate as much as you can.

This means using export tools in your current location (e.g. wikis, CMS, document repositories, etc), and also Confluence's excellent built-in Word import functionality.  There is a Universal Wiki Converter which is not supported by Atlassian because it's a 3rd party tool, but the fact that the link for it takes you to a place on the Atlassian domain should tell you they think it's useful.  It doesn't work on every wiki, but if it does work for your wiki it will save you a lot of time.  If instead of, or as well as, wikis you've got lots of Word documents to import, the Confluence Word importer is brilliant.  It's really good at importing formatting and layout, as well as features like tables, images, links, headers, footers and diagrams, and it's really quick to boot.  Oh, and it will create new pages every time there's a heading in your document, if you want it to, even down to being able to set the level at which new pages are created (e.g. it will create new pages every time it finds a Level 1 or Level 2 heading, but ignore any other heading levels).  The Word importer has saved me huge amounts of time. 

Before you start importing things:

• Plan your space structure before you move things in. 

It's pretty annoying having a structure set up and working only to find it doesn't scale to accommodate what you're transferring and you have to move things around again.  This is where a content person is really helpful if you're a technical person.  Content people are good at the structure and layout of large bodies of information, and we'll help you analyse the user needs and get it right.  Confluence's space and page structure is deceptively simple because this simplicity means it's very easy to create monolithic spaces with one massive list of alphabetically ordered pages.  But people don't connect information alphabetically, so creating a space directory, page trees and label taxonomy using the guiding principles of good information architecture will make it much easier for people to navigate.

• If multiple people are bringing stuff in, agree on common naming conventions, page structure, and labels.

There's no getting away from the fact that if a team of technical communicators will all have slightly different ideas about conventions and structures, then a motley crew of various resources will all have very different ideas about conventions and structures.  Even if all the people importing are technical communicators, and especially if they're not, set agreed standards for page naming conventions, page structure and labels BEFORE anyone imports anything.  Otherwise it'll require a massive remedial exercise later on to standardise everything, or if this isn't done, your Confluence instance will be a mess.

• On the subject of labels, use them to say where a Confluence page came from, e.g. wiki name, shared drive, SharePoint, or wherever.

If you've never gone through this kind of process before this might seem superfluous, but believe me, it's not.  No matter how careful you are when you're importing, you or someone else will want to check the original source because "it doesn't look right" or "I'm sure we used to have more information on this in the old system".

And while we're talking about it:

• Keep your old repositories for at least 6 months, just in case. 

Transfer them to a portable hard drive that an admin locks in a secure cupboard if necessary, but don't "move and delete" because you'll regret it (even if no-one needs the back up you'll always be fretting that someone will need the back up).  If after 6 months (or whatever time frame you're comfortable with) you haven't needed the back up, get rid of it.  But in the meantime, keep them so that you can answer queries about "it doesn't look right" or "I'm sure we used to have more information on this in the old system" (see above) and so that you can do "idiot checks" to make sure you've got everything.  Pro tip: Every time you import something, move the original to a new location that mirrors the structure of the original location.  That way you can be sure everything's been imported.  If you can't realistically move it, mark it with (something like) an underscore at the beginning of the title.  This is also helpful when multiple people are importing things as it stops people importing the same thing twice.

Despite the fact that you're keeping your old repositories for a while:

• Bring as much metadata over as possible, especially who last edited [whatever you're importing] and when.

When you create a page in Confluence, your name is sat under the title as the creator.  This isn't useful for people who want to ask questions of whoever created the original content.  Pull the metadata from wikis or documents (manually if necessary) and add it to the page, preferably in a default location such as just under the title. 

Having said that:

• Consider adding smaller documents as attachments rather than extracting the contents. 

This will greatly reduce your import time and allow you to turn off your old system much quicker.  You can then turn the attachments into actually pages over time if you want to.  I wouldn't advocate using Confluence as a document library because really it's very poor at that.  But in terms of speed, you can drag and drop multiple documents at once into the Attachments page (or the Attachments macro) and if you're pushed for time to remove things from the old system this will work as a temporary measure.

Finally, a couple of "human" issues:

• Manually porting things over can be boring and a lot of people won't do it right because of this.  Only get people who really enjoy doing this kind of repetitive, finicky work, otherwise you'll spend huge amounts of time correcting the work of people who got bored 10 minutes after they started.
• As soon as you can turn off the old systems, do it.  Or at least restrict access to them.  People are creatures of habit and lots of them will keep using the old systems until it's literally not possible,
• It's going to take longer than you thought.  Take a deep breath, settle in for the long haul and don't get downhearted.  You can and will do this, and it can and will be a success.

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. 

Why Do People Like Writing Documentation?

If you want to annoy a technical writer, nothing hits the spot quite like hearing "Man, I'm so glad you write the documentation! I know it's got to be done, but boy, it's soooo boring!"

The technical writer-approved responses to this are:

A) smiling through gritted teeth and then seething for the rest of the day,
B) barely-concealed sarcasm about the commentator's level of (il)literacy, or
C) physical violence. 

Personally, I veer between B and C depending on the number of witnesses and the size of the person making the comment. (Ok, B.  But I spend the rest of the day wishing I knew kung fu and imagining C.)  But why, I hear you cry?  We ARE grateful for those weird people that sit in the corner and enjoy typing! Seriously, writing documentation sucks! 

Oh. Dear. God. *imagines nunchuks*

Right, listen to me.  I like writing.  I like learning things.  I like organising my thoughts on paper.  I like helping people.  I like helping people by learning about things and then organising my thoughts on paper using the power of writing.  This is fun for me, and for my fellow writers.  You think I started this blog to make myself rich?  Are you kidding me?  I write this blog because I LIKE WRITING, and I know a bit about technical writing in an agile environment, and I wanted to help writers in similar situations by sharing my knowledge.  You see how that works?  I'm helping people by organising my thoughts on things I've learnt and writing it down for other people to read.  Just because YOU don't like writing - you big philistine - doesn't mean that everyone else doesn't like writing either.  Writing is the mark of an educated civilisation.  Writing well is the mark of an educated person.  Education is a good thing.  You hear me? A GOOD thing.

We don't become technical writers to get rich (damn you, JK Rowling), get famous (hello, Shakespeare) or get people into bed (Lord Shelly, you dog!).  Those are benefits for novelists, playwrights and poets, not those of us who help other people work out how to bypass the bad design and hurried implementation of people who are glad they don't have to write the documentation.  We live in a gift economy, where the most important thing we have is our knowledge and our skills.  Tech writers don't get paid as much as devs, but we're still fortunate enough to do better than a lot of people if we work for any decent company.  As such, being able to show people how to do something they couldn't work out for themselves is a valuable commodity because generally speaking tech people don't care for overt shows of material wealth.  What gets respect is knowledge and skills, and boy oh boy do your technical writers have those in abundance.  You just know too little about what we do to realise that sometimes.

And, while we're on the subject, writing documentation is not dorky, or nerdy, or geeky.  Well, not any more than any of the other technical professions we work with day in, day out.  For us, writing things, organising concepts, helping people, these are what get us out of bed in the morning and we won't apologise for it.  Some people like playing WarHammer, some people take pride on being able to quote every line from every episode of the original Star Trek, and some people are so obsessed about their coffee that they're happy to drink something that's been defecated by an animal.  Some people do all of those things.  The Venn diagram of these people and people who work in software development contains a lot of overlap, so just remember that next time you think a writer is a bit geeky or weird for not wanting to write code instead of natural language.

Although, to be fair, developers are definitely not alone in their bemusement of why people would want to be technical writers.  When someone asks what you do and you say that you're a technical writer, there's often an awkward silence while they try to think of something to say, and that's mainly because the stock answer of "Oh, that's interesting + [question]?" seems to get stuck in their throat.  Because not only do they not find technical writing interesting, they find it SO uninteresting that they can't even maintain the social civility of lying.  At least with a lawyer or salesman you can make a crack about their lack of morals and know they've heard it a thousand times before, even if you couldn't give a flying duck about the intricacies of their job.

Don't worry, like the weasels in notorious professions, we're also well-used to hearing a stock answer.  It's just that for technical writers that stock answer is "Ah.....um.....", and believe me, as people with both morals and a soul that we'd like to keep relatively unsullied, we're much happier with that than poorly-disguised contempt. Still, to help you, here's a few gambits that might help:

1. "That's interesting, is your documentation in the definition of done?  That's a thorny issue at our place."
2. "Yeah, a friend of mine does that too and she loves it!"
3. "Man, I couldn't do that job because my English sucks.  Much respect to people who've got that talent."
4. "Oh, so you teach people about new tech?  That's awesome!"
5. "Really?  Wow, you know I've always thought writers were really sexy....."
   

Ok, maybe not #5.  But the first 4 are all good.

Anyway, having got slightly distracted, back to the issue at hand.  I like what I do.  Scratch that, I love what I do.  Learning stuff, organising that knowledge logically, writing it down for other people - that's like crack cocaine to me.  Yes, I do other things like knowledge management and training people because I'm not a pure technical writer any more, and yes, I love those aspects of my job.  But my love stems from those core desires that all technical writers have: to learn, to organise, to teach. 

That's why people like writing documentation.  

Is Knowledge Management the Same as Documentation?

This is an interesting question.  Traditionally, technical writing covers the production of documentation that explains the functionality of what we can call, in the absence of a better catchall term, technical things that are produced by engineers.  These technical things could be anything from mechanical to electrical to electronic to programmatic.  Technical writers produce documentation that covers the installation, configuration, integration, support, maintenance and usage of these technical things.  This isn't a new phenomenon either; writers have been producing what could be called technical documentation since well before the industrial revolution (a particular favourite being Kitab Aniq fi al-Manajaniq (كتاب أنيق في المنجنيق, or An Elegant Book on Trebuchets) which was written in 1462 by Yusuf ibn Urunbugha al-Zaradkash).

Knowledge Management (KM) is a much newer profession: it became a discrete discipline in 1991 with the publication of The knowledge creating company by Ikujiro Nonaka in the Harvard Business Review (which you can read online at HBR here).   Although philosophers have studied knowledge for millennia (Plato was writing about it in Ancient Greece nearly 2500 years ago, and he was almost certainly not the first person to do so), they weren't studying it with a view to making sure people captured and shared their knowledge, which is the main goal of a KM professional.  Philosophers were, and still are, more concerned with what knowledge is and the difference between certainly, belief, knowledge, etc, and although that's very interesting from an intellectual point of view, it's not overly helpful in practical terms.  KM doesn't have the history of technical writing, nor does it come from the intellectual highlands like the study of syntax and semantics do (both of which are key to effective technical communication).

And yet because documentation now comes under the auspices of KM in many places, so must technical writing and therefore technical writers.  This makes sense, because if the goal of a knowledge management system is to make sure that the knowledge in people's heads is captured and shared, then you will need technical writing skills to document what is captured.  And in those places where technical writing is not explicitly line-controlled by KM, perhaps because there is no explicit KM function or because KM and technical writing come under different reporting lines (e.g. product management and development), it's still hard to see how you could implement a robust KM programme without your writers being involved in some way.

This though begs the question, does it not? of whether KM is actually just a fancy phrase for technical communication. The goal of technical writing - to explain, elucidate, inform and teach through the medium of written documentation - is one of knowledge transfer through capturing and sharing knowledge.  A Documentation Manager will be responsible for, amongst many other things, laying down standards for information capture, such as information from developers about issues they've fixed; it is a short hop to say that these standards should be slightly expanded to include the capture of other information that needs to be written down somewhere, even if it won't go into explicit documentation sets targeted at specific users.


Of course, KM has its own language: You encourage knowledge sharing, with the aim of building a knowledge ecosystem, a place where the codification of knowledge is performed collaboratively by expert practitioners who can explain and illuminate both their explicit and implicit knowledge, with the ultimate target of having a complete record of the output and metadata of your human capital. KM experts will make references to culture, process and technology forming a tripartite foundation on which a company's knowledge management programme will stand strong for decades, or crumble into the dust. 

But such language is often just a label for a more complicated concept, a short cut for adepts to use in cultured conversation.  The technical writer, when talking about the use of DITA in a single-sourcing environment as part of a content management strategy, is doing no different.  These languages should not be mistaken for the practises themselves; the language may be a point of difference, but that doesn't mean that the practises of a KM professional and a documentation professional are therefore automatically different. A "punt" in American Football is no different to a up-and-under in Rugby Union (the synonym "huge Garryowen" - thanks to the late, great Bill Mclaren - is also identical in practise).

The practises of technical communication and the practises of KM, especially when viewed through the different lenses of their languages, may seem divergent, particularly for the practitioners of each, but the goals and intentions of technical writing and KM are almost identical.  The practises too, cover a lot of the same ground: information gathering, analysis, writing and sharing the result of that writing. However, there are differences between KM and documentation, and the two primary ones are:

• Scope
• Responsibility 

A KM professional normally has a greater scope of work than a technical writer.  Where a technical writer needs to write documentation (which includes information gathering, content creation, editing, and so on), a KM professional needs to be charge of the documentation, delivery method and gap analysis, as well as driving a culture of collaboration, knowledge sharing and training.  Correspondingly, the technical writer will have a deeper knowledge of one aspect of KM - documentation, and all of the attendant skills that are required to produce it - and the KM will have a broader knowledge that encompasses documentation as one (critical) part.

Related to this is the level of responsibility.  A technical writer normally has responsibility for creating content themselves, whereas a KM professional has responsibility for getting others to create content.  Both cases are value multipliers, because the technical writer makes public that which was previously private and the KM professional does likewise, but the KM professional does it by making as many people as possible into value multipliers by getting them to create content and share it.   

Whilst it might seem that the KM professional is therefore more valuable, it is also the case that with this increased reward comes an increased risk.  Content that is created by people who are not trained documenters can be confusing, inconsistent and incorrect; it rarely follows standards for terminology and structure, and tends towards the scattershot approach of "write everything", which means that users have to work hard to sort the wheat from the chaff.  Whilst these problems can be ameliorated to an extent by documentation tools that force users to do certain things (such as templates, mandatory metadata entry, obligatory skins and formats, and so on), there is only so much that automation can achieve.  The return on investment of hiring a professional writer to produce documentation, or at least the most critical documentation, cannot be underestimated.

Another interesting, although perhaps localised, difference is that KM is often seen as a more dynamic role than that of a technical writer.  KM is a collaborative exercise with collective benefits, as opposed to being a job for a specific team, like technical writers, which the collective doesn't always recognise as worthwhile.  This shines a light on part of our psychology: Everyone wants documentation when they don't know something, but few are willing to create documentation that explains what they already know.  In a good KM programme, there is an acknowledgement by the majority that if each individual documents their knowledge then everyone will benefit.  Therefore it is in the interests of the individual to contribute, especially if there is any sort of public register of those that have and haven't contributed. On top of this, the idea of a gift economy comes into play, and people who have the knowledge often like to give it away as an act of largesse to show how much they know. (You may call this ego if you wish, but for me that's too pejorative.)

Where there is a specific documentation team, there is generally no sense of people using a gift economy.  It can become a chore for people outside of the documentation team to have to write things down, because they only see the benefits to others, not to the collective or to themselves, even though the outcome is largely the same.  It's as if they feel they are doing the job of the technical writers for them.  For this reason the KM programme's emphasis on collective responsibility can be more effective.  I won't say much on this here, but I leave it as a point of interest for those who think about such things.


In conclusion, KM and documentation are not the same thing.  Where both are present, documentation is one part - albeit the most critical part - of the KM process.  KM can be seen as a framework in which documentation sits.  Of course, this isn't the only framework and a KM programme is not required in any way to give value to documentation.  But where KM and technical writers work together, KM should provide the direction and culture, and technical writers should provide some of the content and make sure all of the content forms a coherent whole.

As always, your thoughts are welcome in the comments section.