Chapter4- The forms of software documentation .pdf

SOFTWARE DOCUMENTATION AND TECHNICAL WRITING Dr. Hanadi Mardah [email protected] Computer Science Department Umm Al-Qura University First Semester 2024/1446 Chapter 4: The Forms of Software Documentation 2  Content Types Content types are differ...

SOFTWARE DOCUMENTATION AND TECHNICAL WRITING Dr. Hanadi Mardah [email protected] Computer Science Department Umm Al-Qura University First Semester 2024/1446 Chapter 4: The Forms of Software Documentation 2  Content Types Content types are different patterns for building effective and consistent documentation. Different content types help solve different kinds of problems. A use case (also called a business problem or user scenario) is a set of tasks required to complete a goal. Each task is an interaction with your service or systems. Use cases can be created by researching users and finding what goals are most important to them. When you identify the most important use cases for users, you can plan documentation with content types that address their needs. Good documentation describes use cases that help users meet their goals. 3 3 Software Documentation and Technical Writing  Use Cases or User Scenario 4 4 Software Documentation and Technical Writing  Content Types Content types help you write the specific kinds of documentation your users need. Each document type serves a specific task, user archetype, or learning preference. The most common content types for developers and shows you how to assemble them into a documentation plan. Although each of these content types has its templates and guidance, you should shape them into what works best for your users. 5 5 Software Documentation and Technical Writing  Code Comments The most basic content type for developers is code comments. Beyond describing what your code does, code comments document design decisions and tradeoffs made when writing code, describing what you did and why you did it. The tenets for good code comments are to: Keep them brief Make them relevant Use them liberally, but not excessively Code comments alone aren’t enough to help your users understand a system at a summary level. To help users understand why your code exists—the problems your code solves and why it matters—you can write a README. 6 6 Software Documentation and Technical Writing  READMEs A README is a single text file, often written in Markdown, that summarizes a collection of code, usually at the top level of the code repository. You can also write READMEs for important subfolders that require additional summary or explanation. Code A README contains basic information like: Ø What the code does at a high level Ø How to install it Ø Troubleshooting steps Ø Who maintains the code Ø License information Ø A changelog Ø Basic examples Ø Links to more in-depth resources and documentation 7 7 Software Documentation and Technical Writing  READMEs v A README needs to be concise, Listing 2-1 provides a README informative, accurate, and up-to-date. As template. you continue working on code, make sure A paragraph or two that encapsulates what the code does at a high level. to keep the README current with the ## Installation 1. changes you make. Along with serving as 2. a cheat sheet for the code repository, a 3. 4. README often serves as the basis for 5. more comprehensive user-facing ## Examples3## Troubleshooting ## Changelog documentation. ## Additional resources ## License information 8 8 Software Documentation and Technical Writing  READMEs Guiding users through first impressions and first-time user experience is the critical role of getting started documentation. Getting started docs are your opportunity to help users get up and running and to build trust with your users that you will guide and support them with good resources. As you write a getting started document, some questions you should ask yourself are: Ø What are the quickest explanations of what this service is and what its core features do? Ø What are the simplest steps to install and use your product? Ø What are the most important questions new users will have? Ø What are the cool things they can do with your service? 9 9 Software Documentation and Technical Writing  Conceptual Documentation The next content type is conceptual CONCEPTUAL GUIDE documentation. Conceptual documentation The first paragraph, which introduces the concept explained in the document. helps users understand the concepts and ideas Overview behind your service. It describes how your service works for users. Conceptual content Give a technical overview of how the concept works. Describe any additional sub-components or related should avoid implementation details. concepts in sub-sections. Meeting notes, design documents, whiteboard Related Concept 1 diagrams, and internal documentation are great... source material for your service’s conceptual Related Concept 2 content.... Keep conceptual documentation brief and Additional resources concise, especially if you’re using conceptual List any related documentation, including tutorials and information to set a context for a procedure or how-to guides that implement the concept. tutorial. 10 10 Software Documentation and Technical Writing 1- Writing to Teach- Tutorials 11 Software Documentation and Technical Writing 11  Writing to Teach- Tutorials A tutorial is a procedure that teaches users how to achieve a specific goal and help users test an integration without implementing real code. Good tutorials provide users with an environment they can use for learning and may even offer test data or tools to use. If your tutorial includes more than ten steps, you’re trying to solve for a use case that’s too complex, or you’re combining too many actions in one document. Long, time- consuming tutorials make it less likely that a user will successfully finish. If you can’t condense a long tutorial and the service itself is too complex. There may be steps that should be combined, automated, or omitted from the service—and that’s a conversation you should have with the product developers. Tutorials follow principles of instruction that assume that the users progress in skill and confidence with a program. With teaching, the intense contact between teacher and learner requires a different design of text and graphical info than for guidance or reference. 12 12 Software Documentation and Technical Writing  Basic Features to Teach Software Skills The following are the basic features of a document designed to teach software skills so that the user can perform them by memory: Introduction, which emphasize problem solving. Tutorial begins with basic function and builds to advanced. The modules organizes a document and helps users identify discrete tasks to learn. Document uses examples from the user’s workplace. Overview helps orient the learner to the task. Icons help the user see where to click and reinforces the text. Explicit instructions limit the user’s options. (click cancel – you do not need to create a new worksheet-) Graphics shows novice user exactly what to do. Steps keep the user focused on one task a time, using workplace examples. 13 13 Software Documentation and Technical Writing  Guidelines 1. Identify skills you need to teach Plan tutorial around tasks, and for each task, list the program skills that the user need and put workplace task and program skills together. 2. State objectives as real-world performance Objectives should appear as skills that the user should learn as a result of the tutorial. ex. “ in chapter x, you will learn the following skill…” so tell the user what he or she will learn from the lesson and put the objectives in measurable terms ex. “ this lesson will teach you to create a drawing with three colors”. 14 14 Software Documentation and Technical Writing  Guidelines 3. Choose the right type of tutorial a. The guided tour: a guided tour presents an overview of the program features to a user unfamiliar with them. It is an overview of program features that informs and persuades the user as to the usefulness of the program in a low-interaction environment. It focuses on the entire program capabilities and user actions like main screens and useful commands. It occurs online or in print, it consists of a booklet of the important features of the program. 15 15 Software Documentation and Technical Writing  Example of Guided Tour 16 16 Software Documentation and Technical Writing  Choose Right Type of Tutorial 3. Choose the right type of tutorial b. Demonstration, design a demonstration when you want to illustrate some specific parts of a program, perhaps for a particular user, usually, you use an example of the program, often a limited version of the program. It is a more focused presentation of a particular program function being performed, which tends to be passively viewed by users. The tutorial instructs the user to start the program and tells the user what commands to use to perform the demonstrated procedure. 17 17 Software Documentation and Technical Writing  Example of Tutorial Demonstration 18 18 Software Documentation and Technical Writing  Choose Right Type of Tutorial 3. Choose the right type of tutorial C. The quick start, It differs from the previous two forms, it is for experienced to advanced users with domain knowledge who want to get going with a program. It involves significant user interaction with the program itself, and rarely uses examples. It is a form of documentation that is generally aimed at more advanced users and provides the basic information that one needs to dive into the program and interact with it on their own. This type help users get down to work and cover the basic and advanced procedures. It consists of one page or folded cards that explain how to start the program and list of commands. 19 19 Software Documentation and Technical Writing  Example of Quick Start guide 20 20 Software Documentation and Technical Writing  Choose Right Type of Tutorial 3. Choose the right type of tutorial D. The guided exploration, this kind of tutorials contain instructions for the user to “try out” commands which encourage exploration of the program, but don’t limit the user as to exactly what to do. It contains a little discussion to give the users the experience they need. It guides a user through a procedure but allows for some experimentation on their own. Usually, it takes a form of short tutorial manuals, may or may not provide some scenarios (examples to follow), may include objectives and summaries to give the user direction but do not constrain him to learn specific commands. 21 21 Software Documentation and Technical Writing  Example of Guided exploration 22 22 Software Documentation and Technical Writing  Choose Right Type of Tutorial 3. Choose the right type of tutorial E) The instruction manual, A manual usually accompanying a technical device and explaining how to install or operate it. It focuses on users who intend to operate a program or expect to have to learn a number of complicated commands and functions. It attempts to teach as much of the software as possible through a full series of interactive lessons. It consists of lessons, each focuses on specific objective, usually tied with specific set of command. This type of teaching relies on the principles of accumulative learning, you learn one skill before you take on another, more advanced one. 23 23 Software Documentation and Technical Writing  Example of an instructional manual 24 24 Software Documentation and Technical Writing  Guidelines cont. 4. Offer highly specific instructions, your instruction or lessons should focus on a specific scenario or problem that the user would recognize. Some examples of specific instructions include. Specific data, Tools, Screens, Commands. It should include a specific details not a generic instruction such as “enter a number” instead “enter 1234”. 5. Give practice and feedback at each skill level. Pace(walk with slow regular steps) the tutorial, keep lessons down to a bout 10-12 minutes each, this will help them concentrate well. They may get called away during a training session, so give them a chance to quit during a session without losing data and having to restart later. 25 25 Software Documentation and Technical Writing  Guidelines cont. 6. Try your tutorial, test it in a lab. You should base your testing on the objectives of the tutorial. Design the test, also to focus on the design elements such the cuing system, the effectiveness of the graphics, and style of writing steps. If you do not have a real user try to mock-up the situation with someone of similar background as the user. 26 26 Software Documentation and Technical Writing  Designing Tutorials Designing tutorials: You should start with the knowledge of how tutorials work, and when the user need them. You should know when to use this form of documentation, and when to apply others. The users only have the tutorial section to rely on to learn a program, no teacher or advisor to talk to, so the document has to do the work of these. Such “self instructional” documentation, should take the place of teacher, textbook, workbook, lectures, question and answer session. The tutorial section of the manual becomes the teaching environment. 27 27 Software Documentation and Technical Writing 2- Writing to Guide- Procedures 28 Software Documentation and Technical Writing 28  Procedural Documentation The next type of user content is procedural documentation. Procedural content includes tutorials and how-to guides—anything from installation instructions to API integrations. A procedural document shows readers how to accomplish a specific goal by following a set of structured steps. A single step should describe a single action that a user takes. People read documentation to solve a problem or accomplish a task, and they want to do so as quickly and effectively as possible. Procedures consist of how-to-do-it explanations, but also require how-it-works and why- it-works overviews. Our job is to balance these elements to meet user informational needs and to make them efficient and effective in their workplace. Guidance information, also known as step-by-step instruction or procedures, makes up the heart of all task-oriented documentation system. 29 29 Software Documentation and Technical Writing  Guidance information Information you need to provide in an effective procedures: Introduction emphasize creativity and user control of the program. Screen shows the user result of actions. Tips help the user find ways to use the program efficiently. Tables help the user decide what options to exercise for this step. Elaboration tells the result of actions and tells the user where to get more information. 30 30 Software Documentation and Technical Writing  Tips When Writing Procedures Give readers the essential information - information that will help them complete the procedure - first. Limit the use of screen captures. Make the steps as brief as possible. Write in present tense. Keep procedures as short as possible. If a procedure becomes extremely long, see whether you can logically break it up into two shorter procedures. Reduce the number of decisions a reader has to make. If necessary, move some decision points outside the process steps or redesign the software interface for more consistency across platforms. State conditionals clearly at the beginning of sentences or paragraphs, so that readers can skip text that isn't relevant to them. 31 31 Software Documentation and Technical Writing  How-to Guides How-to guides are the core type of The first paragraph introduces the core concepts and gives an overview information required for this procedural content. A how-to guide shows guide. how users can solve actual business Prerequisites problems by performing specific steps List any steps your users should do before they follow the steps in this guide. with your service. Steps How-to guides are a true differentiator for 1. 2. your users: a single document that helps 3. them build a solution to their problem. 4.... While, tutorials focus on learning, a how- Next steps to guide is based on action with users Link to additional documentation the user should implementing real code. follow after doing the steps in this guide. 32 32 Software Documentation and Technical Writing  Guidelines 1- Relate the Task to Meaningful Workplace Activities. A procedure is a step-by-step series of commands for accomplishing a meaningful operation. 2- Determine how much information your user needs. A rich procedure needs more visuals, more explanations, more options, describe more results. A sparse procedure on the other hand require only the repeating of the steps in the task description. 3- Choose the appropriate instructional format: -Standard format, which contains steps, notes, screenshots, and other elements left justified in one or two columns in sequential order from first to last. -Prose format, puts steps in sentences and paragraph forms making it look and feel more conversational over Standard format's command approach. -Parallel format, shows a screen with the fields empty and parallels the field names in the steps that follow. 33 33 Software Documentation and Technical Writing  Guidelines 4- Follow a rhythm of exposition, which means a pattern of steps, note, and illustration. Such as: - first I say what will happen. - then I give the command for the first action. - then I say how the program will respond. - then I tell the next step. The basic idea of rhythm of expositions lies in the action/response pattern. Computer programs work in the way: take an action, the system respond, and these events get repeated over and over again. 5- Test all procedures for accuracy, Evaluative test, which means that after you finish the procedure, you have an actual user, or prototype of the user, or yourself as a last resort to perform the steps. 34 34 Software Documentation and Technical Writing  How does a procedure work? A procedure works, guide the user through a series of tasks to a designated end. The following discuss how each of those parts contribute to the overall task orientation of the procedure: -Task name, use performance oriented language such as “opening a file” or “printing a card”. - scenario, it means a small story or narrative in a setting, it tells or reminds the user what the task will allow him or her to accomplish in a working setting. Scenario has a dual function of introducing the task and suggesting workplace application. Base the scenario on information you discovered while writing your program task list and analyzing your user. - steps, steps tell the user what to do, it tells the tools to use and the action to take with the tool. “use the mouse to select”. Often users does not read the explanation that go along with the steps, so you should make the steps as self sufficient as possible. 35 35 Software Documentation and Technical Writing  How does a procedure work? elaboration, with elaboration you share the following with your user: possible mistakes and how to avoid them. screens, use screen to the following: how to perform procedures efficiently. alternatives such as keystrokes, toolbars. show the partial result of a procedure. definition of terms. show the final result of the procedure to let the user ways to tell if a step has been performed correctly. know where the procedure ends. where else to look for additional info. show dialog box where the user has to make choices. tables, follow these guideline when using tables: show toolbars indicating which tools the user need. keep table simple. show menus indicating what command the user cite the table in the text. need. use descriptive, performance based column titles. use visual cues for keys or command, or menu selections presented in tables. 36 36 Software Documentation and Technical Writing 3- Writing to Support -Reference- 37 Software Documentation and Technical Writing 37  Introduction Reference documentation, or support documentation, are the look-up and help parts of a manual. They should be organized in a task-oriented manner, not just alphabetically. It is important to consider the correct form and organization method, as well as the user's needs. It takes form such as command descriptions, menu overviews, list of definition, function descriptions, and error messages. While procedural and conceptual documentation educate and inform, reference documentation is all about cause and effect: which actions produce which results. This is also true for troubleshooting. Sometimes users encounter errors or friction, and reference documentation helps them quickly get back on track. 38 38 Software Documentation and Technical Writing  Reference Structure Elements of a reference structure: Function entry, tells what the function does. Declaration , shows how to use the function. Remarks, help the user know when to apply the function. Edge bleed, helps the user find the reference entry alphabetically. See also, helps the user see interrelationship among entries. Examples, apply the entry to workplace uses. Tips, tells how to use the command efficiently. 39 39 Software Documentation and Technical Writing  Guidelines 1. Choose the right form of reference, a. The usual forms of reference, quick reference, along with the procedures in a user’s guide. b. Special forms or reference: - appendices, most people see appendix in book the same way they see an appendix in their body: as useless structure. But in fact, the appendix in a software manual often contains some of the most valuable info relating to the use of the program, it gives document writer a place to put all the high detail, technical info, that technical person would want and use in the workplace. 40 40 Software Documentation and Technical Writing  Appendix It contains info that relevant and useful, but not essential to all users. If you examine an appendix in software manual you will find: Error messages. Filenames and extensions. Troubleshooting tips. Matrixes of compatibility with other programs. ASCII charts showing word processor key-combination. Printer driver charts showing capabilities with various printer brands. 41 41 Software Documentation and Technical Writing  References Examples - Readme files, are text documents containing important initial information, including installation details or tips, information updated or added after the manual was created, new features in an updated program, revision histories, errors, file descriptions, content of directories, and compatibility requirements.. - innovative forms: are documentation that are presented in special formats, such as foldouts, posters, and flip-cards. The advantages of special formats like flip- cards are that they improve readability, contain a lot of information, make information more accessible, and use elements like color to help locate information. - keyboard templates and short forms (job aids), it consist of very brief reminder that attach to key-board. Usually limited to defining keys, they can stick to the keyboard or overlap the keys. 42 42 Software Documentation and Technical Writing  References Examples 43 43 Software Documentation and Technical Writing  References Examples 44 44 Software Documentation and Technical Writing  Guidelines 2. Decide what to include a- commands, Commands are the instructions used to work with a program. These include meanings of special function groups, explanations of set commands, definitions of format commands, instructions for using utilities, explanations of toolbars, and definitions of macros. b- interface elements, it refers to the part of screen or command line that the user sees and has to read and manipulate in order to put the program to work. It would include the following: explanations of menus, definitions of keys, labels of screen regions, and explanations of rulers. C- definition of terms (glossary), glossary defines terms used in the manual. Glossaries may define terms that relate to the software itself or to the subject addressed by the software. concept that relate to the software such as shell, masks and terms such as general ledger. 45 45 Software Documentation and Technical Writing  What to include in a single reference entry? When developing reference documentation, writers should also consider the content to include in each reference entry. They may include, conceptual information, structural information, how-to information, or technical information. - Conceptual information explains the term and its function. - Structural information explains how the term relates to other terms. - Technical information describes the programming information related to the command. The content of each reference entry should be based upon the user's needs. 46 46 Software Documentation and Technical Writing  Guidelines 3. Establish a pattern Whatever the content of reference entries, the same pattern should be used for each entry. This helps the user to become familiar with the format. Topics included in patterns of reference entries include definitions, explanations, examples, step-by-step directions, and warnings. - definition, tell what the command or function does. - explanation, tell how to apply the command or function. - example,give an example of the command or function in use. - step-by-step, present abbreviated steps for using the command or function. - warning/cautions, let the user know what problems might a rise. 47 47 Software Documentation and Technical Writing  Guidelines 4. Organize the reference section - alphabetical organization, with functions starting with append command and ending with xcopy. In the case of topics areas, or command sets, you may put them in simple -to-complex order or you might choose to start with the more abstract one, progress to greater and greater level of concrete. - menu-by-menu, according to how the user sees them in the program, you start with main menu then secondary menu. Present each menu, and then, in the subsequent pages, describe each of the commands in the order they appear on the menu. The strong advantage of this is its reinforcement of the task orientation of your work. - context-sensitive, you can organize your help section according to the context within which the user ask for help. The organization of the work really, does not make that much difference with context sensitive reference, because the user only sees one or two screens at a time. 48 48 Software Documentation and Technical Writing  Guidelines 5. Show how to use the reference info: In many cases, your document required no instruction. Maps of menus or summary of commands represent a self-explanatory reference page. However, you should tell the user - usually- in the introduction, the pattern you intend to follow, so he or she establish it in his/her mind, set up the right expectation, and it will serve as a reminder of how you organize each entry. Such an introduction should explain: who should use the info, which type of users. how you organize the info, alphabetical or menu bye menu. element of each entry, list element of each entry. relation to other section of the documentation, cross reference to other parts of the document. 49 49 Software Documentation and Technical Writing  The psychology of the reference user Users do not like to waste time looking things up in help functions or manuals. They also dislike having to leave a screen to search for their information. Well-designed documents will cater to the values of efficiency and immediate usability for these users. As a writer, be sure to establish a pattern and follow it. A good rule to follow generally, the more structure there is in the information, the more usable the entries are within the document. 50 50 Software Documentation and Technical Writing  References Examples - How do I get to the function? The experience user need to know how to find a function more than any other info, to get them going. (access information) -what does the function do? The experienced user very brief explanation of what the function does. (function definition) -what other commands do I need to know about? The user wants to know how to use the command along with other commands, as well as how to get out of trouble. (associated commands) - when can I use the function? User needs to know if there is a special condition exist when using a command, such disk drive compatibility or file size limits. (qualifications or special cases) -How do I use the function well? The experienced user wants to make the most out of the system and needs to know any short cuts or efficiency measures that apply. (Tips) 51 51 Software Documentation and Technical Writing  References Writing Software Documentation, 2nd edition, Thomas T. Barker, Longman Publishers, 2004 https://www.slideshare.net/slideshow/software-documentation-ch-5-writing-to-support- references/229482546 https://www.cs.kent.edu/~nalhinda/SD/SD-CH-1.ppt 52 52 Software Documentation and Technical Writing