THINGS YOU NEED TO KNOW ABOUT USER DOCUMENTATION DOCUMENTATION BEST PRACTICES

Transcription

1 5 THINGS YOU NEED TO KNOW ABOUT USER DOCUMENTATION DOCUMENTATION BEST PRACTICES

2 THIS E-BOOK IS DIVIDED INTO 5 PARTS: 1. WHY YOU NEED TO KNOW YOUR READER 2. A USER MANUAL OR A USER GUIDE WHAT S THE DIFFERENCE? 1 3. TYPES OF TECHNICAL DOCUMENTATION 4. TECHNIQUES FOR RUN BOOK CREATION 5. TECHNIQUES FOR REFERENCE GUIDE CREATION 2

3 CHAPTER 1 DOCUMENTATION BEST PRACTICES WHY YOU NEED TO KNOW YOUR READER? Before you start working on your end user documentation make sure you are paying enough attention to the target audience of your piece of writing. People are not alike: they might be of different ages, occupations, their levels of knowledge are most likely to vary as well. The needs and goals differ from one person to another. You should consider all the above mentioned factors to be able to produce a truly handy guide. However, don t try to guess or assume the info about your readers as you might easily overshoot. If there is such an opportunity, it would be useful to communicate with the target audience of your end user documentation and ask what goals they want to achieve while reading it. This very information is the key to success! If an enduser doesn t find your manual professional, nothing will stop him from thinking the same about your organization. 3

4 4 REASONS TO KNOW YOUR AUDIENCE: 02 YOU WILL CLARIFY THE PRIMARY GOAL OF YOUR WORK 01 YOU WILL KNOW HOW TO PRESENT AND FRAME THE INFO Approaches vary from one group of users to another. While beginners find it easier to comprehend if there are visuals such as screenshots, advanced users, in turn, will appreciate if you include more thorough information on a product. Vocabulary of the documentation also depends on this factor. If you know the goals of your customers you know your own goals. Every piece of end user documentation, a user guide in particular, has its purpose. It has been created to satisfy somebody s needs and no surprise that readers look for the answers in it. 4

5 4 REASONS TO KNOW YOUR AUDIENCE: 04 IT WILL HELP YOU DECIDE ON A USER GUIDE FORMAT 03 YOU WILL BUILD A STRONG IMAGE OF A TRUSTED VENDOR Although it is believed that nobody ever reads user manuals, sooner or later there will be an emergency when one will need to refer to this help guide hoping to find an answer to the question which bothers them. If it does not meet their needs, they might form a negative opinion about the usability of your product. Every specific documentation format is aimed at a reader with this or that level of knowledge and product awareness. Without knowing your target audience you won t be able to choose the format of a user document. There are two main types of user guides: a functional guide and a procedural guide (read more in chapter 3). 5

6 CHAPTER 2 DOCUMENTATION BEST PRACTICES A USER MANUAL OR A USER GUIDE WHAT S THE DIFFERENCE? One of the basic skills of a technical writer is the ability to choose meaningful headings, captions and titles. So, it s quite important to define the meaning of some words and phrases in order to be able to use them effectively. There are a variety of terms that are widely used for naming user documents, such as user manual, user guide, reference guide, instructions etc. Some people claim that the terms guide and manual are synonyms, so they use them interchangeably. Others, in turn, are sure that there is significant difference between these words. Both explanations of the terms show us such types of documents as explaining materials containing detailed instructions, often step-by-step, as well as associated images (in a software industry screenshots of program s interface). 6

7 ALSO CONFUSED WHEN HEAR THE TERMS USER MANUAL AND USER GUIDE? 7

8 USER GUIDE A short reference on some particular aspects of a software product. The examples can be all kinds of How-to, Installation and Getting Started guides. Can be created both in a form of written documents (e.g. troubleshooting guides with step-by-step explanations) and in the form of different media, such as help video. USER MANUAL Traditionally a large book containing detailed information on many different aspects of a program, including processes and major features. This kind of document is expected to consist of more than one chapter built in a fully structured sheet with a table of contents, numerous sections, and an index at the end. 8

9 However, in a modern IT world technical writers don t always take those things into account and call the instructional documents according to some other criteria: today the word manual is often associated with something old-fashioned and boring, so end-users are less likely to read such documents. the word guide refers to the software industry describing computer tasks, while the term manual serves for explaining hardware-related tasks. the term guide is considered to be in fashion nowadays: considering a guide as something short and up to a point, there is the opinion that creation of user guides is faster and end-users perceive them more positively. 9

10 With this in mind, technical writers prefer guides to manuals. Indeed, such big companies as Microsoft, Apple, IBM tend to name their pieces of documentation user guides, or sometimes user s guides regardless of the fact that these documents have all the characteristics of manuals. LET S CONCLUDE A term user guide is more often perceived as something useful and a manual is believed to be something boring and useless. Even though this tendency is not relevant in all situations and probably will not make difference in the world, yet it is essential to clearly understand what each type of technical document means. 10

11 CHAPTER 3 DOCUMENTATION BEST PRACTICES TYPES OF TECHNICAL DOCUMENTATION Choosing the relevant format for your guide is a crucial step for the whole process of creating user documentation. Carefully defined format may significantly influence the further success of your document. That is why you need to identify the particular kind of a guide for every target audience. FUNCTIONAL GUIDE OR PROCEDURAL MANUAL Functional guide explains the whats of a software product, while procedural guide provides you with all the hows of different features and procedures. Thus, the beginners are mostly interested in functional 11

12 details, whereas experienced ones are ready to dive deeper in all possible procedures that are there. Let s have a closer look: Functional manual is an introductory technical document which gives basic information on a software product. It provides a description of each individual Choosing the relevant format for your guide is a button and text field. crucial step for the whole process of creating user Procedural guide is a comprehensive document, explaining how to perform a particular step-by-step procedure with the product help in order to solve a single problem not being distracted by all other fields in a product s interface. Procedural guides don t just give the basic knowledge about a product, but also explain what the better way to do something is. In other words, a functional manual gives explanations on what the software product does, while a procedural guide contains information on how to perform all these whats. The decisive criterion here is the target audience of the software documentation. Functional guides are aimed at beginners while procedural guides best meet goals of tech-savvy users. 12

13 AND MORE There are also various types of procedural guides and functional manuals. User guide Reference guide It is a primary manual for all users of a product. It consists of directions for installing and using software or hardware. You won t find a detailed description of different aspects of the software, but only some basic information on how it can be used. A user guide may also contain some theoretical knowledge of product s functions. As compared to user manuals, it is a more detailed reference of some particular parts of software. It is a more advanced version of a user guide, created for the users who are familiar with the software but need some details or a quick guidance. They are usually organized alphabetically (for example, by keywords) but not around user tasks. 13

14 Run book Novices will struggle to comprehend them. Another kind of a guide, containing an extensive set of instructions to maintain the daily routine of a computer system or network, documented by an IT professional or administrator. They exist with the aim of making all the procedures replaceable in case of emergency and help keep the system infrastructure in one place. Similar to other types of guides, workflows in run books are described in a form of the detailed step-by-step guides. To save time, IT professionals tend to automatize this process by using process documenting tools. e.g. StepShot Training manual A training manual provides just basic information on some software. It usually goes as a first step in the learning process, followed up by details, included in reference or user manuals. 14

15 books are described in a form of the detailed step-by-step guides. Installation guide It is a set of step-by-step instructions on how to install a particular software. It usually comes in both versions a digital and printed ones. The reason for this is that there may not always be an access to a digital version of the enduser document. Two or more types of guides are frequently combined: user and reference guides are most likely to be mixed with each other. Several guides can make up a single manual. 15

16 CHAPTER 4 DOCUMENTATION BEST PRACTICES TECHNIQUES FOR RUN BOOK CREATION Writing a run book might become easier if you know the particular tips and tricks. Here are 4 techniques which will help you document like a pro. TIPS & TRICKS 1. DON T PROCASTINATE A run book tends to be quite an extensive piece of IT documentation, so producing one requires a considerable amount of time. The last 16

17 thing you want to do is to leave this job low on the totempole as it would turn into a real nightmare later on. Remember, imparting technical knowledge in details is a really complicated and demanding thing to accomplish. Instead of leaving it for later try working on your runbook consistently and regularly while documenting all the procedures and operations of the system. This way, when the time comes, you ll find it much easier to gather them into one runbook. 2. THINK OF YOUR READER The things which are obvious to you, might be a foreign language to your reader. Make sure your approach to creating this helpful manual is as detailed as possible and you don t miss any steps. All of the info in the run book should be easily interpreted and understood. The best way to explain all the procedures and operations is in a step-by-step instruction set, complete with screenshots and other visual aids. 17

18 3. CHOOSE THE RIGHT TOOLS Run books tend to be extensive, but the right tools can make creating one quicker and easier. Make sure you don t waste the time on performing particular tasks manually when they can be done automatically. For instance, in order to document operations and procedures, it s better to refer to a process-documentation software. 4. START DOCUMENTING WHILE DEVELOPING Cooperation of Development and Operations teams is crucial in the process of producing a run book. This kind of a help-document is mostly written by an IT Operations team after the development is completed. It is recommended for developers to write a draft run book in order to avoid the operability problems in the future. 18

19 If the software development team writes a draft of a run book or an operation manual, many of the operational problems, that are typically found during pre-live system readiness testing, could be caught and corrected earlier. Matthew Skeleton Operability can Improve 19

20 CHAPTER 5 DOCUMENTATION BEST PRACTICES TECHNIQUES FOR REFERENCE GUIDE CREATION A reference guide is a detailed reference of some particular part of software and is created for users, who are familiar with the software but need some details or quick guidance regarding certain aspects of a product. Therefore, there are particular requirements which are crucial for this kind of a guide. So, here are the top 5 tips that will guide you through the process of creating an efficient reference manual. 20

21 TIPS & TRICKS 1. MAKE IT SEARCHABLE The main characteristic which makes this end-user document special Ais excellent reference searchability. guide is aindeed, detailed reference of some referring to this document the reader expects to quickly find what he/she is keeping an eye out for. The best solution for this is to make an index where all the articles are put in alphabetical order and are easy to find.t of software. It is a more advanced 2. MAKE IT STAND-ALONE MATERIAL Every article in a reference manual should be an independent document, which can be understood without reading the whole guide. This means, you can read a reference guide in any order and it won t affect your comprehension. So, choose the right format (functional manual or procedural guide) depending on what you want to explain and make it stand-alone help material. 21

22 3. MAKE IT DETAILED A reference guide is aimed at advanced readers, who it is assumed already know the main concepts. That is why all kinds of details are highly welcomed. So, while describing different processes and functionalities of software don t be afraid to dive deeply into a world of Aadditional reference facts. guide is a detailed reference of some particular part of software. It is a more advanced 4. ANNOTATE THE VISUALS The main focus of a reference guide is to put visuals, in most cases screenshots. They are considered to be 22

23 truly useful elements, because the best way to explain interface is to show it. As it was already mentioned, reference guides tend to be detailed, so visuals are also expected to contain as many details as possible. That is why you have to spend A some time annotating your screenshots and afterwards reference complement guide is a them detailed withreference short and of up-to-apoint particular descriptions. part of software. It is a more some advanced 5. BE ACCURATE Along with being detailed, a reference guide also needs to be precise. Make sure, the information you included is relevant and is kept up to date. On the top of that, the terminology you use in a reference guide should be especially accurate. By this, we mean you need to determine the vocabulary for the guide and use one term for one feature, without using any synonyms and similar terms. Otherwise, a user might get confused and, as a result, not find your user document advantageous. 23

24 Brought to you by stepshot.net 24