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

5 Things Writers Need From Developers

Developers don't like writing documentation in the same way that cats don't like having a bath. There might be the odd breed of cat that likes a bath, just like there is the odd developer who likes writing documentation, but generally cats and developers are quite predictable when it comes to baths and documentation.

But people like being able to get necessary-but-onerous jobs done with the minimum of effort, time and thought, and developers are no different.  So here is a list of 5 things writers want from developers. 
 

Clarity 

Don't provide a steam of consciousness brain dump about the work item you're documenting.  List things in some kind of order.

Accuracy

Can't remember why you added a radio button to the UI?  Don't make up an answer.  When you're not sure, tell us you're not sure.  If you know the name of someone who might know, give us that name.  We'll do some legwork for you.  But don't ever make stuff up.  

Timeliness

Not just about when you get the docs to us, but when you write them.  Yeah, the next piece of work you've been looking forward to is much more interesting that documentation, but tough luck.  Your memory is fallible and you will forget details of the work you've done.  So either document as you go, or at least document before you move on to the next piece of work.  It will save you and the writer a lot of pain later on as they have to spend time interrogating you and your terrible memory.

Completeness

Also known as 5WH: What, When, Who, Where, Why and How.  WHAT was done, WHEN was it done, WHO did it, WHERE was it done, WHY was it done, HOW was it done.  If you take nothing else away from here, remember 5WH.  

Consistency 

Provide the same information every time in the same place.  Create a template.  Ask the writer to create a template for you.  Get every developer to use the same template and save it in the same place - a new Confluence page in the Release space for every work item, in the comments of the JIRA item, in a dedicated Slack channel for that release, in a README for every GitHub pull request, wherever works for the team.  Then do the same thing every time.


Some notes on the above:

• There are pieces of information that it's just common sense to include, like the names of people who worked on something and the numbers of linked work items.  Forgetting to include these makes you look anything from unprofessional to incompetent.

• There are pieces of information that the non-writer may not think need to be included.  Ask the writer if they want that information included.  This is one of the ways a template really helps.

• Writers hate it when their work can be called into question, especially if it's because a developer has fed them some made-up information.  Reputation is important to writers, so don't make them look bad at their job. (This is a pretty good rule of thumb for all interactions in your life.)

• Being part of the "too cool for school" culture that mocks people, especially developers, who write documentation is boring, unprofessional and frankly pathetic.  It's part of the "bro culture" that everyone hates (apart from bros, obviously).  It should be embarrassing to you if you get your kicks from ripping on other professionals in your office.  Stop it.  If you're reading this then hopefully you're not that kind of developer.  Spread the professionalism around your office as required.

• Developers who write good docs are normally the better developers in the office.  Writing good documentation requires you to be able to step into someone else's shoes, as does writing good software.  The most respected (and best paid) developers I've worked with over my career have significantly overlapped with the developers who write good documentation. 

• When all's said and done, developers need to communicate what they've done, whether they want to or not.  Learn how, become a better developer, become a better professional.

 

The Craftsmen and the Chart-Makers

We don't make anything any more.

That lament has followed us through the years as a ghost floats above his killer, never seen with the fullness of the eye but always hovering as a mocking, aggressive reminder of what we've done to ourselves.  We've killed our ability to make things, outsourced it to the non-Western world in return for self-righteousness about the lack of pollutants in our post-industrial lands, while we wring our hands about the plight of the people in those barren places where the machinery has cooled and seized.  Statues of steel and rust in yellow, grey and brown, abandoned as a warning to our children, mnemonics to those of use who saw them in their prime, moving, growling, far too large to ever be killed, or so we thought. 

And who is to blame, cry all? 

The politicians! The corporations! The environmentalists! The unions! The liberals! The elites! 

Each one says, "But, 'tis not us! We only wanted a clean, technologically-advanced land, where people are educated, work is skilled and life is good! Why do you blame us for the best of our intentions?"

And the politicians blame the unions, the corporations blame the environmentalists, the environmentalists blame the market, the unions blame the liberals, the liberals blame the elites, and the elites melt into the ghost that haunts our waking and takes what's best from our sleep.

But many have never seen a post-industrial land, let alone an industrial one.  Their concern for what we make is limited to discussions about tax, custom tariffs, import and export ratios, figures upon figures arranged in industry-approved charts of all kinds, a blanding of the sweat, effort, sacrifices and pain of the makers into black digits in a white cell.  Not for them a life steeped in the stink of manual labour, the ache of muscles from a 12-hour shift, the primal satisfaction of using the power of your body to provide for your family.  These are things that belong to a different age, an age of flat caps worn without irony, holidays to the seaside, outside toilets, knowing your neighbours your whole life, living, dying, generations of people, within the same county border, the same town, the same village, the same factory or mine or mill, the same house. 

A German and his English colleague once talked with horror of man becoming a mere appendage of the machines, workers being no longer the means of production but lowly attendants on those mechanical monsters that have taken over the effort, the sweat, the pride of making things.  A portent of what is to come?  The chart-makers delight in this thought, this hope, for all they see is minimum costs and maximum production, a line on a graph that moves smoothly and predictably in their favour in a mathematically optimal way.  The messy meat variables are being replaced with pristine metal constants.  Is this not utopia?  Is a land built on the cool predictability of the voiceless machines not better than one uncertainly sustained by the chaos and noise of a directionless mass of writhing limbs?  So much chaos.  So much noise.  So much complexity, too much complexity, a rabble of variables that moves the chart further and further away from a prediction and closer and closer to being no more certain than a prophecy.  This is not what the charts should show.

The chart-makers say: These lives are an anachronism!  We don't need them.  We need the figures to balance in our favour, and if they balance in our favour then the anachronisms will have work to do somewhere else.  And eventually the figures always balance in our favour.  Eventually, but always.

All hail the chart-makers, for they shall inherit the earth! 

We don't make anything any more.

But we do.

The chart-makers just can't see it.

......

When steam relegated the horse to a luxury, the wailing sounded a keen note.  Blacksmiths, tanners, farriers, your services are no longer needed! You shall drive trains, mend engines, cast metal, all to feed the new metal equines!  Things will be more efficient, quicker, more productive.  We can do the work of 10 men with 1 man!  Those who tallied ledgers laughed excitedly at all the black ink they would need for their account books; surely red ink would be the preserve only of those unfortunate enough to find themselves on the wrong side of this revolution?  But red ink continued to be produced, and the crafts that had been practised for a thousand years were slowly forgotten.

Then, a century hence, the wailing begun again.  Steam?  A historical irrelevance! Internal combustion and electricity are far more reliable, efficient and predictable. No more water towers to fill and maintain at every station, no more coal stokers, no more steam engineers!  And these crafts also fell into abeyance, replaced with electricians and mechanics who each did the work of 10 men.  And still the red ink was needed by those who tallied ledgers, their initial excitement gradually worn away as their predecessors' had been, a sour cloud of unfulfilled expectations emanating from accounting rooms everywhere as those messy, unpredictable variables stubbornly refused to yield to the new technological constants that were supposed to do away with the chaos of manned labour.

After another 70 years or so, enough time had passed for those doomed to repeat history to believe that their time had come.  Computerisation meant that the electricians and mechanics, with their specialised training, knowledge of arcane physics and militant unionism, were no longer needed.  The mechanical was becoming the digital.  Slowly, gradually, inexorably, the levers of day-to-day power were moving further away from men whose hands were covered in dirt to men whose hands had never known such indignity.  The blacksmith had become the metal worker, who had become the mechanic, who was becoming the engineer, and soon he would become the developer.  The revolutions were coming ever quicker; even the accountants has started to work more with charts than ledgers, and it was only a matter of time.  The digital revolution was here and the remnants of the old revolutions needed to be purged to make way.  The mine, the mill, the factory, these were legacies from a past time that had no place in the new order.  Again the keening wail, frustrated and helpless in the face of relentless progress, again the inevitable loss of the skills and the communities that formed around them. And as before 1 man did the work of 10 men, and those who were becoming chart-makers thought nothing of this except as it affected the colour of the font in their new digital ledgers.

Now, we stand as our predecessors did 30, 100, 200 years ago, a decade or more after the last revolution and staring the chart-makers squarely in the eye.  We are caught frozen in a moment of calm before we tip one way or another as the momentum of the world shifts to compensate for the weight of the now obsolete craftsmen that have been pushed to the side.

But in their absence a new breed of craftsman has arisen.  The architect, the graphic designer, the UX specialist, the technical writer - these are the modern stone mason, printer, fresco painter, scribe. Plant maintenance is now IT Operations, the mechanic is the developer.  Where once we made horseshoes, now we build containers, where before we listened to our machine to find their problem, now we step through their innards and debug them.  Just as in preceding revolutions, the change has opened as much opportunity for us messy variables as it has closed previous avenues.

Of course the chart-makers would claim this was their certainty all along.  Opportunity for all!  But this time the opportunities can be grasped by people using the very tools that have pushed their existing skills to the side and that's not the doing of those who would measure progress using graphs.  For graphs measure things, but that measurement has meaning only to those who find it meaningful.  To those who measure things not by lines or trends or bars, but integrity, dignity and human relationships, the chart-makers' obsession with these numbers is a measure only of the distance between them and the craftsmen.

The chart-makers glide through white corridors, cradling the magic screens that give them purpose and value, to glass-walled sanctums of design and certainty.  Outside these numerical monasteries the craftsmen toil, designing, sweating, thinking, building, drinking, testing, checking, laughing, smelling, living, messy variables that defy the digital constants to produce the magic that runs the screens.  The craftsmen know that the numbers are malleable, because the craftsmen make the magic that shows the numbers. 

Everything the chart-makers do is allowed only by the craftsmen.  Every trend-line, pie chart, scatter graph, presentation, calculation, prediction and report, everything they drive, everything they wear, everything they use, their entire world is predicated on the craftsmen, because the craftsmen are everywhere and their magic has seeped into every item, object, tool, process, and system. 

We don't make anything any more. We make everything.

But the divide between craftsmen and chart-makers is wide, too wide for either side's truth to bridge. 

So the chart-makers continue, bathing in the sterility of their quiet, calm, rational numbers.   And when the next revolution comes and the digital craftsmen feel the impotent rage of obsolescence, the chart-makers will point proudly to their charts and proclaim "We were right!".  The brave new world will once again forget the skills of the craftsmen from this age but the trend-lines will keep going up.

The charts don't lie.  They never lie, not to the chart-makers.

What's the Biggest Challenge You Face with SharePoint?

I recently had a conversation with someone that went something like this:

Him: "So what do you do then?"

Me: "I'm a Knowledge Management Consultant.  I'm currently helping a client implement SharePoint."

Him: "Oh, that's interesting.  We've just started using SharePoint and we're struggling with getting the right branding and styling on our publishing site.  Any tips you can give me on working with their CSS?"

Me: "Not really, I tend to work on the content management and collaboration parts, rather than the publishing side of it. But the Microsoft help material is very good and I can point you...."

Him [interrupting]: "What do you mean, you don't do publishing sites? I thought you said you were a consultant?"

Me: "I am, but SharePoint is..."

Him: "So you don't know what you're talking about then?"

The conversation went downhill from there, as my interlocutor almost, but not quite, accused me of lying about what I did and got increasingly irate and frustrated. In the end we parted company with him still muttering and me shaking my head ruefully.

Now you might instinctively think bad thoughts about my ill-tempered friend, but that would be a knee-jerk reaction.  He was clearly struggling with a complicated and powerful piece of software, and meeting someone who might be able to bring some light to the shadows must have gotten his hopes up, hopes which I promptly dashed.  It's only natural that he was frustrated, even if he didn't necessarily express that in the most constructive way.  What's more instructive about this encounter is that it represented a microcosm of the way an entire enterprise often feels about implementing SharePoint.

If you've encountered SharePoint before then the likelihood is that your experience hasn't been overwhelmingly good.  I've met more far more people with negative things to say about SharePoint than I have people with positive things.  It's like the England football team - depressing, confusing, poorly performing, promising lots and delivering little.  But like the England football team, SharePoint's individual components are good, yet the sum seems to be less than the whole of its parts.  To continue this analogy one stage further, the management just doesn't seem able to turn a collection of good things into a better coherent whole.

The question is: Why not?

Let's start an answer to that with the obvious point that SharePoint is large and complicated.  If you have SharePoint then you're going have Microsoft Office, which increases both the size and the complexity by a significant factor.  Office itself can be pretty difficult to get to grips with as a whole, when you've got both client and online versions, as well as lots of tools that weren't in the traditional Office package of a few years ago, like Sway, Planner and Video.  Then there's OneDrive, which is actually just a personal SharePoint site with a front-end, and Power Apps, Flow and Delve.  The sheer number of these apps is dizzying, and they all work together if you want them to, and each one is a whole book and training session on their own just to get comfortable with the basics.  Even programs as venerable and well-know as Word, PowerPoint, Excel and Outlook have lots of functionality that most users never know about or haven't got to grips with.  Then you add a powerful electronic document and records management system like SharePoint on top of all that and dear Lord, where on Earth do you even begin?

This alone is enough to put a lot of people off, and not just users.  Designing, implementing, training and supporting that kind of enterprise-level suite of applications, with its mind-boggling array of options, parameters and functionality, is not a job for the faint-hearted or workshy.  For users it can be even more daunting because they're not supposed to be the experts and usually have very little time to dedicate to learning these tools.

The biggest part of this problem is that often the people deciding to use SharePoint underestimate the investment of time and resources needed to design, implement and support it, and they seriously underestimate the investment of time and resources needed to train users. Many a C-level decision-maker has seen a demonstration, or worked in another company with a successful SharePoint implementation, or seen that it's a highly-recommended tool by a relevant professional body.  These are all valid reasons (although not sufficient on their own) for choosing SharePoint, but they're not valid reasons for thinking that SharePoint is easy, simple or quick to implement and maintain.  If you've seen SharePoint working well then you can't even begin to imagine how much work has gone into making that happen.

It's worth saying as well that when users struggle with SharePoint it's not always because it hasn't been implemented well.  SharePoint is so large that you can't even hire a consultant direct from Microsoft that knows all of it to a significant degree.  It's also not the most intuitive experience, which makes learning it harder.  Training users is always easier when an application has obvious signposts and markers for the users, because once they've got a rough idea of how things work they can generally find their way around and work out how to do things using these signposts and markers.  But there are plenty of areas in SharePoint where these signposts and markers are missing, often because a certain feature or parameter is "owned" by one application within SharePoint/O365, so you can only get to it from that application.  This means a lot more rote learning is required to know how to do things.  On an application as large and complicated as SharePoint this means that the learning curve is high, which acts as a significant barrier to adoption across a business. 

When you take these problems together - the size, the complexity, the difficulty learning it - it becomes easier to understand why my frustrated friend felt like he was banging his head against a brick wall.  He's most likely up against a deadline, he's faced with a suite of applications that is so large it's very difficult to know where to start, and when he does start the amount of learning to be done must feel insurmountable.

All of which leads to the reason that many companies struggle to have a successful implementation of SharePoint: It's not a one-off implementation, it's an ongoing process of training, learning and incremental advances for the entire life of the application.  

Every user needs to be trained, and not just with a 60 minute introductory session.  Every new starter has to be trained.  Existing staff have to have access to refresher training.  Training material needs to be updated as new functionality is released.  Content and working practises have to be analysed so they can be successfully migrated.  Deletion, retention and preservation policies must be decided and implemented from the very start.  Metadata must be applied to migrated content and added to all new content.  Workflows must be designed, created and added.  Security must be applied.  And throughout all this you have to deal with the change management aspects by engaging the users, communicating the plans and timelines, quelling fears, and listening to concerns.  If you can do all this, and still meet your success criteria then you'll have a successful implementation.

SharePoint is not an application, it's a long-term commitment of people and time.



(Note: A cardinal rule on this blog is that I never discuss current or previous clients.  Nothing from this post should be inferred about any company I've worked for; as always this is a general discussion about issues that we find in our industry.)

The Basics: 12 Steps to Writing a Great Knowledge Base Article

Knowledge Base (KB) articles are normally technical and as such in the realm of the technical writer.  Where an FAQ might encourage you to try a new product or feature, a KB article helps a user get past a problem when they're already using that product or feature.  So if FAQs represent "sales self service", KB articles represent "support self service".  

With this in mind, you should focus your initial efforts on writing KB articles that will answer the most asked support questions.  This will provide the greatest return on investment for your documentation.  Once you've built up a library of articles, you should try to move to a position where new KB articles are written in response to incoming customer questions.  Ideally, if a customer asks a question once, and the answer isn't publicly available, you'll publish a KB article answering that question within a short period of time

But how do you write a good KB article?  Well, the basics of writing good documentation don't change, but there are a few things which are more important when writing KB articles.  Let's got through them below.

1. Know the subject

First and foremost, don't publish an article unless you're certain it's correct.  This applies to experienced staff who think they know exactly how the product works just as much as it applies to less experienced staff.  As an example, I once wrote a KB article on the possible permutations of accounts and permissions that could be setup for a web application and IIS, but I'd misunderstood the scope of the question.  The result was a rewrite that took some time because the people who understood the technical side were difficult to get hold of, and more importantly it confused a couple of customers, which was the worst possible outcome.  This leads directly to #2.

2. Proof read for technical correctness

Get 2 different people to proof read it if necessary.  There's no shame in asking for the input and oversight of people who are more technically qualified or experienced than you.  As a technical writer you are expected to understand technical issues so you can communicate them, but you're not expected to know all of the technicalities of a product better than anyone else.  That's why you have architects, designers, administrators, installation experts, etc.  Use them.

3. Iterate.  Then iterate.  Then iterate again.

Preferably find someone who doesn't know how to perform the actions you're explaining and ask them follow the instructions through.  If they don't understand it first time, or they ask about an ambiguity, alter the article until it's clear and unambiguous.  This is not a negative step, it's a necessary part of writing a good piece of technical documentation.  A KB article can deal with complex issues that can be even more complex to explain, so the first draft of a KB is unlikely to be the last. Write, test, alter, repeat.

4. Don't overestimate the reader's knowledge

AKA Know Your Audience.  If you're writing for a data entry operator then take the time to explain things that seem obvious to you.  Remember, if you weren't knowledgeable enough about the software to write technical documentation about it, you wouldn't be writing KB articles.  You know more than your target audience so walk them through things if necessary.

5. Don't underestimate the reader's knowledge

AKA Know Your Audience part II.  If you're writing for a System Administrator then try to avoid the whole "teaching your grandmother to suck eggs" thing.  It's a tricky balancing act but if the target audience is (supposedly) technically competent or highly knowledgeable then they won't thank you for wasting their time or making them feel stupid.

6. Make it modular

If you find yourself walking through the same process in more than one KB article, then write a separate article that just deals with that process and link to it in future articles.  This saves you time and helps the user by not cluttering up articles with information that's duplicated elsewhere.

7. KISS

The old "Keep It Simple, Stupid" acronym. In the case of KB articles, this means that you should try to capture one task or process in one article.  Don't try to cram too much in, and don't shy away from writing a series of articles that deal with the distinct stages of a complicated process.  At the start of each article in the series tell the reader that they should be familiar with the information in the preceding articles before continuing.  This allows them to feel that they are making progress and allows you to write self-contained articles that just deal with the problem in hand. 

8. Step-by-step

Don't explain a process in a paragraph.  Use a numbered list, and make 1 numbered point = 1 step.  As a rule of thumb, if there is more than 1 action in 1 numbered point then turn it into 2 numbered points.

This goes hand-in-hand with points 4 and 5 about knowing your audience.  If you're writing for System Administrators who know the product, don't be afraid to write:

"1. Log into the application and navigate to screen x"

Equally, if you're writing for potentially inexperienced users don't be afraid to write:

"1. Log into the application."
"2. Navigate to screen x.  In a default setup this will be located at System > Parameters > screen x"

Generally paragraphs should be used to explain something from a conceptual perspective and numbered lists should be used to explain actions and steps.

9. One Step, One Screenshot

If you write an article with 10 steps, use a good screenshot for each one if it will help the user.  A picture tells a thousand words when you're trying to understand something new.  Users aren't short of the bandwidth needed to download a 20kb png file and I know that the use of screenshots is controversial, but don't preclude them on a point of principle.

10. One Screenshot, One Lawsuit

I can't say this enough: Check your data.  I have seen a KB article published by a colleague who'd taken screenshots using a live database, and those screenshots included identifiable information about customers.  If you have access to live databases, or, as if sometimes the case in development teams, a customer database provided for the purposes of testing, then check, check and recheck your data.  If in doubt, create dummy data, and if you can't then obfuscate any data or consider not using screenshots.  Using live or customer data is a one way ticket to a lawsuit for your company and quite possibly the sack for you.

11. Quality, not Quantity

Yes, it looks great if you bang out 20 KB articles in an afternoon, but it doesn't look so great a week later if 19 of them have been the cause of support tickets.  You're supposed to be helping support, not making more work for them.  You can't rely on a proofreader to weed out every mistake, because it may be that you're the person who's supposed to be an expert on whatever it is you're writing about (this is especially the case if you're not a technical writer and you're adding KB articles).  Writing KB articles is not a fast and easy way to look good.  It is difficult to write well, and even more difficult to write well at speed.  Take your time, think about what you're doing, focus on getting it clear and correct.

12. Spell check is not optional

If you're a technical writer you'll know this, but if you're not then hear this: You can't spell.  Seriously.  Technical writers do this for a living and we spellcheck everything.  Learn to love Word and its spell checking, grammar checking, and little squiggly lines.  These is no excuse for a spelling error in a KB article and it will make you look incompetent.  It will also make your company look incompetent and reflects badly on everyone.  Don't be the person who makes your users wonder how on Earth your company can write decent code if they can't even use a spellchecker.

KB articles are a great way to take the load off support and give customers the power to fix their own problems.  Get it right and you'll find the rewards far outweigh the costs.