Title: DIY Technical Authoring

Author: Bob Schmidt

Date: 06 January 2019 16:14:37 +00:00 or Sun, 06 January 2019 16:14:37 +00:00

Summary: Alison Peck shares some of the tricks of her trade.

Body: 

As a freelance technical author, I develop manuals, online help, tooltips tutorials, videos, simulations and other forms of ‘user assistance’. Throughout this article, I’m going to refer to user assistance (UA) to refer to this type of ‘documentation’ to distinguish it from ‘developer’ and ‘marketing’ documentation, both of which are very important in their own right but which have very different purposes.

I love learning new things, and that includes getting involved in how people are using the software you all develop. As you may imagine, I’m keen for a professional technical author to be involved in UA. However, I’m a pragmatist and I know that not all organizations share my view… and even when they do, there are times when something needs to be done and the technical author (for whatever reason) isn’t available. With that in mind, I thought it would be helpful to offer the people given the task a few pointers to help them do a good job.

First things first. To do the job effectively, you need the answers to the following questions:

1. When and why do people want to use the different features the software offers?
2. What is the most frequent and most effective way of completing a task, and are there any times when an alternative route through the software will be followed?
3. What is the existing level of knowledge of the different people using the software – both in terms of general IT-literacy and in domain-based knowledge? And for the latter, do they know enough?

But you all know that, right? It’s what your use cases are built on. People want to achieve X, so you develop feature Y that enables them to reach their goal. It’s obvious – and usually the software does that very well. For some reason, though, the documentation doesn’t always do the same.

People use software to do something

Technical authors worth their salt know that (most of the time), you want to give instructions on how to do something – task-based instructions, not feature descriptions. That hasn’t always been the case – back in the mists of time (the 1980s), the user manual often described the interface. Section headings like ‘The Properties dialog’ and ‘The New Order page’ were common, and the content would often have mostly been along the lines of: “The five menu options are: File, Edit, View, Sort and Help. The File menu contains…”. When that still happens today is often because some pre-sales material (or some developer documentation) has been ‘repurposed’ to form the user assistance. This can work, but only if either it’s been written with that use in mind or you’re prepared to substantially edit it.

A good starting point for UA is to list the things people want to do – remembering also that most people go to the UA when they are stuck.

What are the tasks?

You probably know these already. You have your use cases and (hopefully) some knowledge of the subject domain. Often, though, your use cases are too granular (or, at least, the ones I’ve seen tend to be).

Use cases list separately all of the different instances under which a task may want to be done – making sure all are considered – whereas from a UA perspective, these are nuances of the same task. For example, you may have a use case that covers an existing customer creating an order, a new customer creating an order and someone who isn’t a customer trying (and sensibly failing) to create an order. In UA terms, you’re simply ‘creating an order’ and if you can only do so with a customer account, your first instruction is either to login or to create an account (and reference elsewhere for instructions on how to do that).

Depending on the subject domain, tasks may combine into workflows – and the same task may fit into more than one. Personally, I find a spray diagram/mind map a useful tool – it helps me to categorise the tasks as I think of them and make sure I haven’t missed any out.

What sort of information to include?

The next step is to split the information you want to share into three categories. These can be called a number of different things, but for now I’ll pick the terms used by DITA (the Darwin Information Typing Architecture, an XML schema designed for technical authoring tasks) [1]:

• Concept – the background information we all need to make sense of what follows. You can’t start a set of instructions with “Step 1: Click…”. First, people need to know what you’re explaining, under what circumstances they may need to do this task, is this the set of instructions they are looking for… you get the picture.
• Task – the nitty-gritty, step-by-step instructions, usually numbered, and often with far too many screenshots (more on this later).
• Reference – often lists or tables of settings, abbreviations, options, icons and so on.

  Just in case you thought from my comment earlier that I never describe interfaces, I put what I call ‘orientation’ information into this category. For example, if just about every screen has five buttons along the bottom that jump you from module to module, or if tool palettes are managed in a particular way, then that is useful to know. (The information also doesn’t need to be repeated every time you get to the end of a task or open a palette. ☺)

If you follow the reference to the easyDITA website [1], you’ll see these referred to as ‘topics’ in DITA, as one of the principles behind DITA is ‘write once, reuse many times’ – but even if you’re writing a more ‘traditional’ manual (and you may be surprised how many organisations – and their customers – still want those), thinking about the type of information you have to share is a good strategy.

How much should I include?

As with everything in life, the answer is: “It depends.” It depends mainly on the answers to the three questions I posed at the beginning of this article.

Concept information

If you are providing instructions for a very simple task in a subject domain familiar to the user, a sentence or two of concept information for each task may suffice. This may be a task and domain familiar to just about all of us (for example, ordering something online) or one familiar to the users of that particular software (for example, doctors who are recording medical information – they know what they need to record, just not how). In both those cases, the ‘concept’ simply needs to specify the circumstances (as understood by the people using the software) in which these particular instructions need to be followed. What we are not attempting to do in either case is ‘teach’ the user about the domain. In this case, we can also use domain-specific terminology (which isn’t always the same as application-specific terminology) without explanation.

On the other hand, if you are writing for people who are using the software to accomplish a task outside their normal range of expertise, you may need to teach the user about the domain as well. For example, you may be developing UA for an accounting package used by business startups, who not only need to know what could be done but also what should be done: for example, not only the mechanics of generating invoices but some guidance on best practice as well. The best UA for people in this category gives a lot of guidance on what to choose depending desired outcome or constraints using everyday terminology. One of my biggest frustrations with UA I’m using is when there are two (or three or more) options that clearly state it’s important which I choose to follow but without any indication about which option you should choose when!

You – I trust – already understand who will be using your software. When I join a team, one of the frequent questions I have to ask is, “Will the users of the software know why they are doing this?”

As well as the little bit of concept that introduces a task, you may need some concept information to set the scene for sequences of tasks or workflows. Anything that provides a context for the rest.

Task information

This part of the documentation can be quite formulaic, and the basics are very straightforward. A few ‘rules of thumb’ are given below… but, as always, there are exceptions.

• Prefer the simple present tense over future or conditional tenses.

  The majority of people are ‘doing’ while reading/following the UA: things are happening now. Save the future tense for things that will happen later and the conditional for things that might.

• Talk to them directly, using the imperative (“Click…” or “Select…”) or address them as “you”. For example: “If you forget your password, you must…”.

  This does, however, depend on who you are addressing and who you are talking about; for example, “If users submit the same order multiple times, they must… ” can be confusing if the readers are the users (“Does that mean me…?”), but not if the readers are customer support, trainers or administrators.

• Give instructions, don’t word them as suggestions unless they are suggestions.

  You are giving instructions – trying to be too ‘polite’ can cause confusion. I once ‘translated’ the phrase “You may want to consider setting…” into “Optional: Set …”. A colleague then deleted it as the remit was to simplify instructions, removing optional steps. Turns out it was an essential step in the process!

• One instruction, one step – and an instruction may be simply to review something. (Very small steps may be combined: “From the File menu, select Properties and then Security.”)

  People may be looking for help when they are ‘stuck’ – something is not working as expected, or they don't know what to do. Putting multiple instructions in one step may mean some are missed.

• Don’t number consequences (the windows that open, the messages that appear) – it helps separate the things the user is doing from the results of those actions.

  This particularly helps people who are just refreshing their memory – and not doing it can change a 4-step process into a 12-step one.

• Give all the information needed… but don’t patronise!

  You don’t want people to feel frustrated – either because some vital information is missing or because you’ve told them what they already know. Knowing what is ‘needed’ and what is ‘patronising’ comes from experience – but also from the three questions at the start of this article. You need to set a baseline for IT literacy in your target audience/readers. Can you assume they know the difference between left- and right-clicking? What a scroll bar is for? How ‘obvious’ are the labels and on-screen prompts?

  When I started developing UA, I was told by my boss (who wasn’t a technical author herself) that I had to provide instructions for every field on the screen. This resulted in some very patronising statements, such as “In Surname, type the person’s surname”.

  Do this…	Not this…
  Enter Start Time and End Time using the 24-hour clock.	In Start Time, enter the time the consultation starts. In End Time, enter the time the consultation ends.
  Type the Surname as it should be displayed. To enter accented characters, see…	In Surname, type the person’s surname.
  The form contains 20 questions – you may need to scroll to see them all.	Drag the scroll bar on the right of the window up or down to see the top or bottom of the page.

• If there are options or alternatives, state them before the associated instructions.

  There is no point in reading instructions when you didn’t want to (or can’t) do things that way anyway. Make it clear under which circumstances each instruction should be followed before giving the instructions (especially important when the instructions are long or complex).

  Do this…	Not this…
  To see a preview, click…	Click … to see a preview.
  Windows only: Change user account permissions to…	Change user account permissions to… (Windows only).

What about screenshots?

Screenshots can be extremely useful to the users of the UA, and also extremely frustrating to both them and the person trying to capture them. Why should that be… surely a straightforward ‘Print Screen’ will do the job? And aren’t they always helpful?

It’s not usually the mechanics of getting the screenshot that’s the problem – although some dedicated software such as Snag-It [2] or Greenshot [3] does simplify the task. It’s more getting the screens populated with sensible information – that makes sense in sequence – before (or as) you capture them… and coping with late changes to the software. In general, populated screenshots are much better than empty ones as people tend to use them as a quick guide to what should be entered. The format of a telephone number, for example, can often be determined more quickly from a clear example than a convoluted explanation.

Many steps within a task don’t require screenshots, and some tasks may not benefit from them at all. To begin, choose whether you want a non-populated screenshot at the beginning of the task, a populated one towards the end, both or neither. Only add intermediate screenshots if something significant happens that makes them worthwhile – perhaps a change to the options shown. And show partial screenshots if that makes things clearer.

Screenshot tips:

• Take a lot – they are quick and easy to capture, you don’t have to use them all, and you have some source material for a bit of editing if necessary.
• Try to use sensible information – accepting defaults unless you want to illustrate something in particular.
• Save the screenshots in the capturing program’s native format for easy editing, then resave in whatever format you need for the UA. For example, a .snag file [2] enables you to change the annotations at a later date. If you are saving to a standard image format, use .png – that way, you can edit field contents for consistency (you can often copy/paste appropriate field contents from the original screenshot over a new one).
• Screenshots in steps don’t need figure numbers or captions – the step number is the reference point and the instruction is the caption.
• If you have something like Snagit [2], capture a video. It makes a relatively large file, but you can extract individual screens from it – particularly useful if you’re capturing screenshots from a mobile device or want to include steps that may fly past quite quickly.
• If your documentation is translated, limit your annotations to numbers – that way no-one needs to edit the image. Even if they are not translated, text in images is unlikely to be searchable.

What about QA?

You are a much braver (or foolhardy) person than I am if you are happy to release UA without some sort of QA process. As with software QA, there are a number of stages to go through:

• A review by the person who has developed it. Is it complete? Does it still contain ‘placeholders’, marking places for information you didn’t have at the time? Assuming the UA has some sort of table of contents, is it in a logical order? Professional pride means you don’t send anything for further review that you haven’t reviewed yourself.
• A review by the subject matter expert (SME). Do the instructions match the reality, especially any concept information? (The SME will often know if something is wildly ‘off’ or if the step-by-step works but only in the specific scenario the author has followed.)
• A thorough review by the QA team. Nothing beats someone actually trying to use the UA to configure something or to complete a task. This review should cover:
  • Is the information complete and accurate?
  • Is it ‘findable’?
  • Are there references to related information? And to prerequisites?

Everyone has an opinion

This is true about software development, but it’s even more true about natural language. Others may have preferred ways of doing things that are different to your own – and many a healthy debate results. However, people in other disciplines are (I hope) more likely to tell you how something should work than how you should code it. In my field, it’s different. After all, everyone can write, can’t they. …

People don’t just tell you something isn’t clear – they rewrite it for you. That can be the quickest and easiest option – otherwise someone says something isn’t clear, you scratch you head over it wondering what is needed, only to discover you missed out a word. Ask the editors of the ACCU journals… if I spot something, I suggest alternatives. ☺

My advice? Be clear what aspects you want the review to cover. Follow the corporate style guide (or, even better, the one specifically for the UA). Treat ‘rewrites’ as ‘suggestions’ and decide each one individually.

References

[1] Stephani Clark (2017) ‘When to use the Concept, Task, and Reference types in DITA’ on easyDITA at https://easydita.com/when-to-use-the-concept-task-and-reference-types-in-dita, dated 14 November 2017

[2] Snag-It from Techsmith: screen capture and annotating software, which also captures video: https://www.techsmith.com/screen-capture.html

[3] Greenshot, open source screen capture and annotating software: http://getgreenshot.org/

Alison Peck Alison has been ACCU’s Production Editor since 2005 and a technical author for much longer. She works in many sectors, developing UA for software and machinery.

Notes: 

More fields may be available via dynamicdata ..