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.
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.
Style guides cover a multitude of areas and it can sometimes be difficult to separate the purely writing-focused guides from the general UI/UX guides. This is not surprising, considering how much UI/UX, technical writing and comms/marketing are starting to coalesce around the central idea of user focused design. But if you're not working in that environment, or if you are but you still want some purely writing focused resources, it can be a little difficult to sort the wheat from the chaff.
With that in mind, I've put together a list of some useful guides below:
Online
- MailChimp - One of my absolute favourites because they focus on the likely user mood at the point of the interaction, and tailor their writing accordingly. This is a relatively unknown style guide, but it should absolutely be one that you spend time looking through.
- Mozilla - A (relatively) short and to the point style guide that focuses on developer documentation. If you write for developers (SDK, API, etc) then this is an excellent resource.
- Apple - As you would expect from Apple, this is not the longest style guide but it is proscriptive. One of the most useful features is the table that converts "developer speak" to "user speak", so for example "focus ring" for an Apple developer is Highlighted area" or "area ready to accept user input" for an Apple user.
- Google - This focuses on writing for a worldwide audience and as such is concerned with clarity and simplicity above all. If you're writing for a geographically diverse audience, especially one which is not highly technical, then this guide will help you a lot.
- GDS - The Government Digital Service guidelines for the UK Civil Service. Not as easy to navigate as many guides, because topics are provided in an A-Z format rather than curated into groups, but contains a lot of information and is recommended if you're writing in UK-English. (The lack of curation is odd; GDS people are normally very big on user-focused design, and this...isn't. But if you can get past that, the information contained is often difficult to find elsewhere.)
- 18f.gov - The American equivalent of the GDS style-guide, this is focused more on US-English and the needs of federal/state public bodies, as you would expect. But it's comprehensive, well-written and very good on grammar and "correct" writing so even if you're not writing in US-English, it's still a very useful resource. And if you ARE writing in US-English, it's indispensable.
- Microsoft - Microsoft provide one of the best known and popular style guides in print (see below) but this resource is far too valuable to miss off the list. The link takes you to a page with just a single dropdown, from which you can download a PDF style and language guide for just about every language you've ever heard of, and many you haven't. French, German and Russian are fairly obvious, but how about Khmer, Igbo and Xhosa (the African language with the clicks)? If you write in any language other than English then this is probably the single most valuable guide on this list.
Print
- The Elements of Style - The classic book on how to write. The focus is not on software documentation (unsurprisingly, as it was first published in 1920), but not having a copy of this is like being a quantum physicist who's never read Einstein's papers on relativity. Some things are just fundamental to your profession.
- The Economist Style Guide - Another without a software focus, and the first edition was published 30+ years ago, but if you want to write clearly and - according to the Economist - with a little flair, this is the book for you. Its best feature is undoubtedly its effort to focus on real-world examples that are universal in application without being generic to the point of mere common sense.
- The Chicago Manual of Style - If you've only heard of 1 style guide, the chances are it's this one. Now on it's 16th edition, it includes specialised sections on writing for digital technologies, including writing with XML. If your office doesn't have this on its bookshelf, it should be because you've got the next guide on our list.
- Microsoft Manual of Style - A slightly more specialised guide than Chicago, but no less useful for it (and probably more so if you're a technical writer). Unless you write software for Apple and only Apple, this guide will show you why so much software documentation has the style and tone that it does.
- The IBM Style Guide - One of the most comprehensive style guides available for the modern technical writer. It is particularly strong on Information Architecture and content design, but don't let that fool you: this is a standout resource for all writers.
- Developing Quality Technical Information - Another IBM publication and not strictly a guide, but so useful that leaving it off the list for that reason would be petty. There is significant overlap with the IBM Style Guide, but this focuses more on training you and less on being a reference work. Unless you're an acknowledged expert in technical documentation, you'll gain a great deal from this book.
There are lots more style guides out there. If you have a favourite that's not in the list then tell me in the comments and I'll add it in.
This post was inspired by Lori Kaufman's post on How To Geek about adding symbols. She writes a regular column on how to do useful things with common applications, and it's very much worth following.
It might seem odd to label a post about diacritics and ALT codes under "The Basics" when most people don't even know what the word "diacritic" means, nor have they used ALT codes. But you've seen diacritics, and quite possibly used them, even if you don't know what they are, so you definitely need to know how to add them when you're writing. And the easiest way to add them is with ALT codes.
So, what is a diacritic?
(Warning: If you've studied linguistics, philology or a European language to any extent you can probably skip down to the part about how to add them to your documents. For everyone else, read on.)
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. If you ever studied French at school you'll be familiar with accents such as ´ (acute) or ` (grave); accents are a type of diacritical mark. For those of you with a more Germanic bent you'll be familiar with the ¨ (umlaut), but even if you've never spoken a language other than English you should still be familiar with the diacritics in façade and naïve (called a cedilla and diaereses respectively). A good example of how a diacritic changes the pronunciation of the word is "rèsumè" (also known as a CV), where only the accents distinguish it from "resume" (to begin again after a pause).
There is plenty of material available on the use of diacritics if you want to delve into it a bit more (and please do, they're fascinating), but what we're concerned with here is how to add these marks when using standard technical communication tools.
Adding Diacritics to your Content
We'll focus on 3 types of documentation tool: word processing, content authoring, and wikis. Between them, these cover the vast majority of types of tools that are used for professional technical communication (we're ignoring things like JavaDocs or Swagger on the basis that code doesn't have accents). There are a lot of different tools out there, so I'll focus on the following examples:
- Word (word processing)
- FrameMaker (content authoring)
- Confluence (wiki)
Each of these tools provides built-in fonts and/or glyphs that cover diacritics, as will any decent word processing or content authoring tool. Wikis are often a bit different because they have more or less of a GUI or WYSIWYG interface. As a general rule, the less GUI, the less built-in support you'll get. Confluence does have built-in diacritics, but once we've covered the 3 tool examples we'll look at a more general method for typing diacritics.
Word
Word - of course - provides pretty much complete support for every conceivable diacritical mark, of which, when combined with every letter of every currently used alphabet, there are a very large number indeed. For common words like "facade", Word will simply autocorrect them, in this case to "façade ". That will probably cover you for most English words, simply because English has only a small number of words with diacritical marks. But it's always better to know how to do things manually if you have to, so in Word go to Insert on the ribbon and on the far right hand side click the down arrow next to Symbol. On the small dropdown that appears click More Symbols to open the Symbol dialogue:
(For you keyboard shortcut aficionados, you can also access this dialogue with ALT+N+U+M)
By default, this dialogue will open with a Font value of (normal text) and a Subset value of Basic Latin. This will display the familiar Latin alphabet and if you scroll down you'll find lots of diacritically marked letters, grouped into language families. For example, the French diacritics are together, the Slavic ones are together, and so on.
Select the Font you want, if it's different from the font you're currently using, and scroll down the list. You will almost certainly find the letter and diacritic combination you want, whether it's the familiar Latin-derived alphabet, Cyrillic, or Greek. If you want to know the official name of a symbol, click the character and the Unicode name will be displayed under the Recently used symbols box. In the screenshot above, I've selected "Latin Small Letter A With Tilde".
FrameMaker
FrameMaker also provides a way of adding diacritical marks, but in a far smaller range than Word. The list of supported diacritics is as follows:
- ´ (acute)
- ` (grave)
- ˜ (tilde)
- ¨ (diaeresis)
- ˆ (circumflex)
- ^ (caret)
- ° (ring)
- ¸ (cedilla)
(For those of you who did a little German at school, a diaeresis is identical in formation to an umlaut, although they alter the word in slightly different ways). FrameMaker allows you to enter these supported diacritics by using an Escape key sequence. For example, to type an è (an e with a grave accent) you press the Escape key, then the ` (left quote) key, then the e key. Unlike CTRL+ALT+DEL where all of the keys need to be pressed at the same time (i.e. in combination), in FrameMaker you need to press them one after the other (i.e. in sequence).
You can find the list of FrameMaker-supported diacritics and other symbols here.
Confluence
Confluence
lies somewhere in the middle. It provides more diacritics than
FrameMaker, but substantially less than Word. Like Word, you can select
your diacritic from a modal panel rather than with a keyboard sequence
and the following shows all of the diacritics and symbols that are
available to select:
These are good examples of the type of functionality you'll find around diacritics in modern tech comm tools. They range from the comprehensive to the minimal, but they're still better than some applications that provide no functionality at all.
What's the generic way of entering diacritics?
Different applications have different methods for entering diacritics, and different native support, which means more learning and a patchy experience. So for those of you looking for a generic way that will work in any application, you need ALT codes.
ALT codes are a method of writing special characters that aren't represented on the keyboard. Pressing the ALT key (or Option on a Mac) and a number on the numeric keypad will display the special character. For example, ALT+138 will type è, an e with a grave accent. You can find a complete list of the basic ALT codes here. Note that you need to use the numeric keypad - the square of numbers on the right hand side of a standard keyboard - to type these in.
However, there is a little more to it than that, because some ALT codes do the same thing. If you type ALT+0232 you'll get the same è that you do with ALT+138, which seems...odd. What's going on?
An Incredibly Brief History of ALT Codes
Historically, ALT codes were used in early Microsoft computers to access the character set that couldn't be typed using the standard keyboard. The early DOS machines were based on the IBM architecture which used a character set called code page 437, and the ALT codes for these are ALT+0 - 255. In this character set ALT+138 gives you the è. Because this character set comes from the architecture and not the operating system it's known as the OEM-encoded (Original Equipment Manufacturer) character set. (Originally IBM used the ISO 7-bit character set that went from 0 - 127, but the ISO extended it to 8-bit to provide space for non-English characters, which led to the classic 256 character set - known as the extended set - that is so commonly used.)
But 256 characters is quite limited, and other architectures slowly emerged as well, so Microsoft decided to use their own, additional character set, which is known technically as Window's ANSI/ISO Latin-1/ANSI Extended ASCII. This provided additional space for more codes by prefixing them with a 0, and in this Windows-encoded character set ALT+0232 will produce è. You can download an ALT code cheat sheet in PDF format here
(Warning: link goes straight to the PDF) that includes both the OEM-
and Windows-encoded ALT codes, grouped together in useful sections
rather than a numeric list.
Unicode
In modern incarnations of Windows the Unicode 16-bit character set is used, as it's the global standard, but the original OEM- and Windows-encoded character sets are still there and the ALT codes for those still work.
Because the Unicode 16-bit character set is vast (see here for some figures, but as a spoiler there are over 70,000 encoded Chinese characters alone), remembering even a tiny fraction of the codes that represent them is beyond mere mortals. Luckily Windows includes a Character Map that will show you all of the available characters and tell you what their ALT code is. To access this pre-Windows 10, type Character Map in Windows search. In Windows 10 the Character Map is - for reasons known only to Microsoft - hidden away, and you'll have to launch it manually. Hit Win+R and enter charmap, and up it'll pop:
As you can see in the bottom left, the Unicode value is shown for the selected character. To use this as an ALT code just use ALT+[the four digits], in this case 0021.
If you switch on the Advanced view checkbox you'll also be able to choose a character set, group by types of ideograph and, most importantly, search for a character. This is very useful when you've got so many characters to search through. In the example below I've search for "grave":
The Character Map is probably the single easiest way to search for and find the ALT code you need, and will allow you to handle any diacritics with ease.
The history and technical specification of character sets, and how they're used, is a vast topic. What I've mentioned above is the briefest outline of a long, complex and thoroughly interesting subject. If you're at all interested in the topic then these links are good jumping off points:
If you know of other good resources about character sets and encoding for the educated non-developer, put them in the comments.
An occasional series looking at best practice for common documentation tasks and situations.
You work on a project that involves making database changes using SQL scripts. Your customers' DBAs need to know what the scripts will do before they run them. This article covers what you typically need to include in your script documentation.
Before documenting any scripts, make sure you include a warning to your customers to back up their database before running any scripts. Ideally, customers should test the scripts on a test version before applying them to live.
1 - What Database type and version is the script designed for?
Does the script update MSSQL? Oracle? MongoDB? Something else? What versions can the script be run on? Are there scripts that do the same thing for different database types and versions?
For example:
This script is designed for Oracle 10g and later. You can find the equivalent Mongo script here [where "here" is a hyperlink to the Mongo script location].
2 - Do you need any particular permission level or security settings to run the script?
Do you have to have a specific system or object privilege? What user roles should run this script? Is the script likely to impact high-security areas such as users, passwords, personal details, company accounts, and so on?
For example:
This script requires the SELECT ANY TABLE privilege. We recommend that a SYSBDA review the script before running as it will add a constraint to the main USER table.
3 - Which database or schema does it need to be run against?
If your application(s) provide more than one database (separate finance and personnel databases, for example), make it clear which database the script needs to be run against. Provide a warning about running the script against any but the intended database.
For example:
This script applies to the Finance database/schema only. Do not run it against any other databases as there may be unintended consequences up to and including data loss.
4 - What does the script do at high level?
Explain how the script amends the structure or the content of the database. The primary types of change are:
- Add/delete/amend table(es)
- Add/delete/amend column(s)
- Add/delete/amend index(es)
- Add/delete/amend constraint(s)
- Add/delete/amend data
For example:
This script will insert 3 new columns to the User table and populate the existing rows with default data.
5 - What does the script do in detail?
Provide all available information about the detail of the script. This will depend on the type of script, but for adding or amending tables or columns include the following:
- Friendly name
- SQL name
- Primary keys
- Foreign keys
- Nullable
- Data types
- Data lengths
Explain why something is being added/amended/deleted, and ideally link to the release notes for the code change that the database change is required for. If data is being deleted explain why it isn't needed any more; flag up data deletion strongly so that customers can make an informed decision about running the script with full knowledge of what will happen when they do.
There are so many possible combinations that examples would be impractical here. Focus on putting the data into a readable format such as a table. This will also help you make sure that the information provided is consistent.
6 - How will this affect reporting and/or database diagrams?
Provide an updated entity relationship diagram and/or data dictionary. Explain that cusomters will need to amend any database reports - e.g. SRS, Oracle, Crystal, etc - and explain what they'll need to change. This is especially important for columns changes; new tables won't affect existing reports and index/constraint changes will rarely have any impact either. If a table or column has been deleted and replaced with something else, explain the mapping of the data between the old and new structure.
For example:
The new data dictionary can be found on our website here [provide link]. If you have reports that reference the deleted column, please amend them to refer to [new tablename.columnname] instead.
These should cover all of the generic bases for script documentation. Create templates for the types of scripts you need to document, including any bespoke requirements that aren't covered here, and you're good to go! If you think there's something missing from the list, drop me a comment below and I'll add it in.
A concept that comes up regularly when discussing best practise in technical writing is single sourcing. What is single sourcing, and why is it often considered to be best practise?
Single sourcing can refer to any one of the following:
- Creating one document and producing it in different formats (e.g PDF, CHM, HTML, etc);
- Creating one document and using it as the basis for different documents (e.g. Installation Guide, Configuration Guide, Administration Guide);
- Creating a topic or piece of content (often called a "chunk") and using it in multiple documents and/or in multiple places in the same document.
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.
What are the Benefits of Single Sourcing?
The primary benefits of single sourcing are that it:
- Has a single content source to maintain;
- Prevents out-of-synch problems;
- Reduces rewriting of the same information;
- Reduces review and editing load;
- Increases consistency of documentation.
Structured, reusable content also provides an element of future-proofing against new distribution channels such as mobile or social media. A new presentation wrapper will be needed, but the content can still be reused.
An additional benefit is the concept of conditionality. Conditionality means the ability to set conditions on when a particular topic or "chunk" will be added to an output. This can be used to provide customised content to different customers or groups of customers, e.g. standard setup information for a particular sector, or bespoke documentation with a particular customer's or group of customers' configuration in mind. Once the conditionality is set up in your help authoring tool, new versions can be created at the click of a button.
Let's take an example. You work for a company that sell the ACME Budget Software product. ACME Budget Software is designed to help both SMEs (small-to-medium enterprises) and large companies manage their budgets. 50% of the ACME Budget Software product is intended for use by both SMEs and large companies, 20% just for SMEs, and 30% just for large companies. Your documentation can therefore single source 50% of the content, and you can conditionally include the 20% (or exclude the 30%) for the SME documentation and include the 30% (or exclude the 20%) for the large company documentation.
What's the Difference Between Single Sourcing and Multi-Channel Publishing?
If you've heard the term "multi-channel publishing" then you might be wondering what the difference, if any, is between that and single sourcing. There's no concrete agreed answer in the technical communications industry, but this is my take on it (other opinions may vary).
The single sourcing "output" is equivalent to "channel" in multi-channel publishing. The difference between single sourcing and multi-channel publishing is that multi-channel publishing can use single sourcing but doesn't have to, whereas by definition single sourcing is designed for multi-channel publishing (and wouldn't have much point without it). In single sourcing, the content, again by definition, is the same wherever it's published (use of variables not withstanding). In multi-channel publishing the starting content is the same, but the final delivered content doesn't have to be. This is particularly so in the case of different delivery mediums such as printed brochures, blog posts, web help, tweets, and so on.
What's the Difference Between Single Sourcing and Variables?
Single sourcing uses a block of text (including graphics if required), normally a few lines or more. Examples could range from a two line explanation of a field to a full topic on how to complete a procedure. This block of text can be used multiple times within a single document and/or in multiple documents. Variables are a few words, such as a company name, release number, website address, etc, which could change at some point in the future, or need to be different in different outputs. Variables are embedded in your documentation, and when you change the text of the master variable, the text of the embedded variable changes everywhere in your documentation. If you have multiple outputs you can set the same variable to have different values for different outputs. An example might be a different Support desk number for standard and Premium users of a product.
Note: I'm using "variable" as a generic term to describe a few words of text that can be placed as many times are you like within a document. In a help authoring system like MadCap Flare there are both snippets (called text insets in FrameMaker) and variables, and there are important differences between them, but that difference is not relevant to this discussion.
When is Single Sourcing Used?
Single sourcing is useful when you have multiple people or teams working on different documentation for the same product. For example, you might have:
- Technical Writers providing end user documentation;
- Trainers providing training documentation;
- Field Engineers providing implementation and configuration documentation;
- Support staff providing FAQs and knowledge base articles;
- Sales Engineering writers providing tender and demonstration documentation.
In these circumstances, having pre-written and approved chunks of text can save time and effort on the part of multiple people and teams. This gives a good return on investment for single sourcing. In other words, the greater the number of target audiences and the greater the number of distribution channels, the greater the advantage of using single sourcing.
But where a team of writers is working collaboratively on the same documentation deliverables, single sourcing is less useful unless you have tightly proscribed standards and structure for the deliverables. This is partly because writers tend to have their own styles, and unless proscribed otherwise what one writer provides will read differently to another writer. The different styles are not necessarily better or worse, they are just different, but that is jarring for the reader and doesn't allow the reader to develop a consistent expectation of how the document will read. The other reason tightly proscribed standards and structure are needed is because the content needed in one deliverable could easily be subtly (or grossly) different to the content needed in another document. This might be solved easily by using conditions, but often the only way to solve the problem is to rewrite the content. Tightly proscribed standards and structures will either prevent this, or they'll make it obvious before you start a project whether or not you've got existing content that can be reused.
Why is Single Sourcing Best Practise?
DITA is a very popular documentation paradigm, and is designed for single sourcing. This popularity is why help authoring tools normally come with at least some DITA support baked right into the product. For the proponents of single sourcing, the benefits as listed above make single sourcing an obvious best practise due to the efficiency and return on investment that it provides. This is a very popular view.
However, it is not the only view. There is a view which considers single sourcing to be an inappropriate adaptation of the object-oriented code reuse philosophy, and that view generally holds to the idea that writing documentation is necessarily a different type of creation to coding. As such, this view sees single sourcing as lacking feasibility in the real world, at least to the point of providing all of the benefits that proponents of single sourcing claim for it. The most well-known articulation of this view can be found in The Myth of Single Sourcing by Michael Hiatt. You don't have to choose a side - personally I think single sourcing works well in some situations and poorly in others - but it's always useful to understand the counterpoints no matter which view you favour.
An occasional series looking at best practice for common documentation tasks and situations.
This blog is written for several purposes. Some of the articles are the amalgamation of my experiences that I'd like to pass on to anyone who is interested, and some are articles that help me clarify and explain my thoughts on certain topics within the realm of Agile Technical Writing. These cover the majority of the posts here on www.agiledocumentation.co.uk.
But occasionally, I use this blog as an auto-didactic tool when I'm learning about something new. It helps me to organise and manage the new information and connections; as the old saw goes, "if you want to learn something, try teaching someone else". The subject of documenting APIs is a case in point.
API documentation may or may not come under the heading of "The Basics", depending on what area you write about. My background is software documentation, so being able to grasp the basics of API documentation is a requirement for me. In fairness, the basics are easy to pick up, because the principles are the same for all technical documentation (concision, clarity, accuracy, correct audience target) and the practise is uncomplicated (access, inputs, outputs, effects). However, my experience has primarily been with SOAP web service APIs, which is only one of a number of types of web service APIs, which in turn are only one of a number of types of API. So I decided to brush up on some of the API documentation knowledge that I'm missing, and was planning on writing an article covering the basics that I learnt.
Normally, the process of learning starts with Wikipedia (because its technical articles are normally pretty accurate on the basics and it often has a useful list of links for further research) and moves on to Googling overviews, tutorials, etc. This process can last anything from a couple of hours to a couple of weeks depending on what I already know, and how complicated the source material is to get my head around. Then I write about what I've learnt. Doubtless this is familiar to anyone who writes technical documentation for a living.
However, in the case of API documentation I can't do the subject justice when there is a better resource for my loyal readers, and it's Sarah Maddox's blog. Sarah is a Technical Writer for Atlassian and, as I've come to realise, a doyen of API documentation. I'm not too proud to realise that sometimes there is someone who just knows a lot more than me, and communicates it very well, and in this case Sarah is that maven. Start here for a good overview of API types, and then review her API category for more great articles.
In addition, there's a good article from the Parse blog on this subject, and anyone that uses the phrase "carefully crafted with love" to describe their documentation gets a respectful nod from me. You can also find some great examples of API documentation here and here.
If in the future I find an arcane area of API documentation that could use some elucidation then I'll apply myself to that task, but otherwise I'll leave API documentation articles to the experts like Sarah.....
An occasional series looking at best practice for common documentation tasks and situations.
Writers who document software will invariably have to document a code snippet or two in their careers. This could range from the occasional line of CSS in a configuration guide every few years, right up to the full-on, nothing-but-code explanations of the full-time API documenter.
I'll be honest, this post isn't for the API specialists, but it is for those who only have to occasionally format a code snippet, or for those who are looking for a better way. Those writers who document APIs will need to follow proscriptive standards and understand the code in order to provide clear, coherent information to their readers. Those writers for whom code is something that people who can't write in a natural language write in instead - you know who you are! (and you're very welcome here) - may however find formatting code snippets a little daunting.
(In case you've never formatted code before, it's not as simple as just changing it to COURIER NEW. Well, it can be that simple, but not if you want to do a proper job. Code snippets will be read by people who code, so it should look like code.)
Fear not, my friends, for there is a simple way to format code.
Your immediate option, if you have access to them, is to use the same tools as the developers. So for formatting SQL you open up a query writer like SQL Server or dbForge Studio for Oracle, drop the SQL into a New Query window, and then copy and paste into your document. You can do the same with code if you have access to an IDE like Eclipse or Visual Studio.
However, the problem with industrial tools like these is two-fold: Speed and Cost. Industrial tools are not built to open in half a second 30 times a day; they're designed for heavy duty coding, and that makes them less than rapid at opening. And although Eclipse is free, Visual Studio, SQL Server and dbForge Studio are not. As I've discussed elsewhere, people should have the licences they need, and it doesn't seem a good use of your budget to spend large amounts of money on licences just so a writer can format code a bit quicker.
Besides, who wants to have to open a SQL application, and an IDE, and an HTML editor, and an XML editor, and a CSS editor several times a day? If only there was a lightweight, fast, free, easy to use application that would open these files with the odd extensions automatically and quickly, and just format the code for us!
Well, there is. It's called Notepad++ and seriously, it's awesome.
If you're not a particularly technical person, Notepad++ might have passed you by, but it is essentially the Swiss-army knife of coding and it is free, lightweight, very quick, and it will format whatever legitimately extensioned code file you give it with ease. Well, let me rephrase that: The list of programming language file extensions it supports is very large, and the chances of you working on one that isn't supported by Notepad++ is low. All you have to do it right-click a file and Open with Notepad++ - or set Notepadd++ to be the default program for opening the code files you need to format - and it'll do the rest.
Here's an example .xml file opened in standard Notepad:
And exactly the same file in Notepad++:
That is out of the box, default functionality. I created a new text file, wrote some XML in it, saved it, renamed the file to XML.xml, and opened it in Notepad++. All you have to do at this point is cut and paste the code into your document, and you're good to go.
I'll come clean with you on one thing: If you want it to auto-indent code that hasn't already been indented, you will need to install a plugin. But that's not too tough an ask, especially if you deal with existing, indented code. By default Notepad++ will change the indent of the TAB button to the standard indent for whatever code you're working in, so as long as you haven't got long screeds of unformatted code to work with, indenting it yourself is very easy. There is also a very active user community, as Notepad++ is used by millions of people around the world, so if you have questions there's a good chance the answer is available already, or someone will answer it for you if you ask on a forum.
If you've got another tool which you think is as good as or maybe even better than Notepad++, please share it in the comments.
An occasional series looking at best practice for common documentation tasks and situations.
Documenting a bug is a common activity for technical writers who work in production environments. Although every company will have differing standards for documenting bugs, there are key pieces of information that should be transmitted to the customers (internal or external), regardless of your company's preferred style or terminology.
These key pieces of information are:
- Who reported the bug?
- What was happening before?
- Where was it happening?
- When was this happening?
- Why was this wrong?
- What's happening now?
Let's look at these items and explain why they are so important.
Who reported the bug?
Each customer will want to know whether the bugs they have reported have been fixed. That's not to say that they won't be interested in others bugs that have been fixed, but their priority when reviewing your documentation will be to find out if the things that they think need to be fixed have indeed been fixed. To track customer reports of bugs, most companies will use some type of ticket system. Each call to the support desk will be assigned a ticket, and if after investigation it transpires that there is indeed a bug in the system, the development team will add a work item or task to their backlog to fix it. In agile environments these tasks will be completed in priority order; this means that a bug may not be fixed in the next release that goes out. Therefore the ticket number that the customer has been given should be visible in the title or heading for the bug when you document it. This will allow the customer to easily search for the bugs that they have raised with the support desk***.
What was happening before?
It's easy to say "The doohicky process is now working correctly." - and this will be an accurate reflection of reality - but that doesn't really help the customers very much. If the reader doesn't know what the process was doing before it was fixed, they won't be able to perform their own user acceptance testing on the process to make sure that it is now working correctly (bear in mind that "correctly" may be a matter of opinion that customers don't always agree on). It's also important that customers can check to make sure that an incorrect process hasn't amended their data; without knowing what the problem was before, their analysis will take much longer.
Where was it happening?
Not so much a problem in an app with 1 screen, but in any large application it is important to give the customer the default menu path to the location of the problem. For example, Form A > Tab B > Grid C > Column D. Customers want to be able to easily reproduce the conditions in which the bug was occurring, and in large systems you should tell them exactly how to get there to save them time and confusion. It also allows them to disregard the bug fix if they don't use that part of the software.
When was it happening?
This doesn't mean "we found it last Thursday but it's been happening since the last release", which is something a developer once told me when I asked him this question. Rather, it means "at what point in the user experience did this bug occur?". As with the Where, the When helps customers quickly reproduce the conditions in which the bug was occurring so they can test the fix.
Why was this wrong?
For some bugs, such as the application crashing, this question is superfluous. But where a calculation is performed incorrectly, or a process sends data to the wrong place, it might not be obvious to a person reading the documentation why this is a problem. For example, "The doohickey process was only storing data to the current and historical tables." might be an accurate explanation of the problem, but doesn't give any indication of what table(s) the process should have been storing data to. A more complete explanation would be "The doohickey process was correctly storing data to the current and historical tables, but was not storing data to the audit table as per the specified requirement."
What's happening now?
All of the above questions combine to form the description of the problem. This question forms the description of the solution. If you have entered all of the relevant information in the problem section of your documentation, the solution should be fairly simple: one or two lines stating that the problem will no longer occur (e.g. "When Save is clicked data will now be stored to all of the correct tables.") or an explanation of the change in functionality (e.g. "When the doohickey process runs, it will now include [variable x] when performing the tax calculation.").
All of this can be boiled down to: Who, What, When, Where, Why, Now, or as a mnemonic, W5N. If you can remember to use W5N when documenting a bug, you'll always provide most if not all of the information that your customers need to see.
*** - If the bug was found internally, or doesn't have a ticket number assigned to it for any reason, either the bug is documented without a ticket number, or depending on your company's procedures, may not be documented in externally facing documentation at all (on the basis that some company's don't feel the need to tell customers about bugs that the customers didn't know about).
