Planning: Developing a logical structure/format Lesson Aim Develop a format for a work of technical writing that follows a logical structure appropriate to that particular work, PLANNING YOUR DOCUMENT We have all experienced the manual or instructional pamphlet that leaves us completely bewildered. It may be because the diagrams do not appear to match the text, the grammar is incorrect or ambiguous, or there is no clear, logical format. Such documents appear to be, and probably are, poorly or insufficiently planned, Planning your writingis vital. The backbone of technical writing is defining the problem and the desired outcome(s). Then, knowing exactly what the purpose of your writing is and understanding your audience, you can plan how best to achieve the desired outcome(s). For one thing, you will need to determine a realistic ime frame for writing. As the old adage says, ‘time is money’. Itis also likely that you employer will want you to work within a specified budget. When planning, you will need to identify what research is required, and to determine a strategy for acquiring and analysing the research material. You will also need to consider the time you will require to: . Write a draft. : Edit the draft for flow, clarity, logical sequencing, and formatting (to ensure the document is easy to read and visually appealing . Proofread the document (which may be done more effectively by someone else). Creating a Technical Document There are Five Steps to Creating a Technical Document a), Research the document - gather information. b) Plan- decide on the format. ©} Write - create an outline and then write the first draft. d)_ Verify - check the accuracy of what you have written. e) Revise - amend the document before publication. RESEARCHING THE DOCUMENT. All documents require research. Even highly trained technicians writing documents directly related to their field need to carry out some research. For example, by checking the demographics of their audience or double-checking specification data. Since many technical writers are professional writers, not industry-trained technicians, the research phase is imperative to ensure the document is accurate and useable. The writer needs to determine what research is required in order to write a document suited to their audience. They will also have to determine how they will undertake the research. Researching involves gathering as much relevant information as possible, sifting through data to get to the specifics, and then organising and analysing the data. Most writers use a range of information sources including expert technicians (sometimes called ‘subject matter experts’, or SMEs), product developers and marketers, and published literature (in journals, on the internet, reference books etc.), as well as their own first-hand observations or findings. Sources of Data for Research There are two main sources of research data: primary research and secondary research. Technical writers often use both types of research data. Their differences are described below. Primary (first-hand) Research This involves collecting data through laboratory experiments, fieldwork or surveys. Secondary (second-hand) Research This type of research involves collecting data from other researchers who have published their findings. If vou are a novice at technical writing ar know nothing about a product ar service vou are to write about.work through the following steps to kick-start your research . Write down what you know about the product or service. . Write down what your audience needs to know about the product. . Do some background research on the internet and other readily available information sources. . Review your notes then find out who can help fill in the gaps in your knowledge, including expert technicians, product developers and other SMEs, . Set up interviews or send emails or questionnaires to your chosen experts. . Organise and analyse your findings before writing the first draft. Interviewing the Subject Matter Expert (SME) A subject matter expert may be your most valuable source of information, but you must be specificin what you want from them. Always do some background research first, then write a list of questions or topics you need to discuss. If you can, send them your questions before the first interview ~ this will give your SME a chance to prepare his or her answers. Show that you have some understanding of the topic. Ask intelligent, specific questions so that you will get relevant, concise answers. Note or record everything said during the interview. Don’t rely on your memory because you will most likely forget at least some important details. Most SMEs are busy so it may be best to schedule several short meetings rather than one long session. Organise your notes immediately after the meeting, if you need something clarified you'll know straight, away, rather than several days later when the material is no longer fresh in your mind. Send brief emails and submit sections of your outline or draft to your SME at regular intervals so that you don’t get too far off track. Most SMEs understand the importance of the documentation process and will respond graciously to courteous and professional interviews; however, some may resent the intrusion on their work time or may not understand your role in the product’s development. In these cases, be patient, polite and persistent; if that fails, try to find a more sympathetic SME. ‘A breakdown of the types of fine detail you should consider for interviewing outlined, below: The Preparation Stage You should know the target audience for your report/paper etc. You should be aware of their general education level, mean age, gender ratio and typically occupational status and work environment. This will help you pitch the interview correctly. When arranging the interview, ensure the time is mutually convenient and at a location, preferably where you will not be disturbed, which suits the SME. Dress to a similar standard as the SME and present yourself well. Open the Interview Depending on the environment, you will naturally act alittle differently. Try to make yourself comfortable and maintain a polite professionalism at all times. Thank the SME for coming /agreeing to meet with you and mention how grateful you are that they have taken time out of their schedule to meet with you. Introduce yourself slowly and give a brief amount of information on your background. The SME will also expect to hear exactly what you are hoping to achieve from the meeting and how their contribution will be used and referenced. Explain the SME role also, There is the possibility the SME has never been interviewed before in this capacity, so an explanation of their role is a good idea. ‘Ask Relevant and Appropriate Questions The interview is an opportunity to find out significant information. You will be analysing, clarifying and hopefully providing the stimulus for the SME to provide additional information. It is important to remember that you are interviewing because you are not a subject matter expert; you are there to find out more ~do not be afraid to ask questions. Asking questions is wise, it is how you will learn more about the subject matter, and this is your chance to find aut as much as possible You should think about asking questions such as: . What is the purpose of...? . What would you expect to happen when...? . How does that happen...?. wnen ao you ao ...¢ . What do you mean by ..? . Can you please clarify...? . Are there other possibilities for...? . If so, what else can be done to...? Overcome Problems or Deal with Difficult Characteristics If you have not completely followed a step/stage described, you could ask for this to be broken down into smaller more ‘digestible’ pieces of information. (Behaviours which are performed or practiced regularly come naturally to experts; often steps are missed or combined, through no negative intention of the expert, but more through inadvertent thoughtlessness for someone new to a process) This one sounds rather simplistic, but if the SME uses the word “it” frequently, you should ask for Clarification on this — doing so removes the potential for ambiguity. For particularly long interviews, you can welcome or encourage breaks at any time. This will enable both you and the SME to have a mental rest from intense questioning. An example of when this might be required is if the SME asks you a question e.g. “sorry, what was that?” or “I don’t know, can | come back to that later?” Alternatively, if you feel rushed, pause - try to slow down your breathing and/or take a deep breath Ifyou lose your thought process, don’t panic. Explain you have a relevant question or point of view which is relevant to the current discussion, but you will need to/would like to come back to that later. This is a simple way to come across as in control, even though you know within yourself that you lost your place momentarily. At this point you may suggest a break too; this one is to clear your head. Ensure Effective Note Taking Puta heading at the top of each page you write on ~ make your notes as clear as possible. You may think to have your questions numbered, and then have a corresponding numbered answer sheet. If the SME is talking too fast, simply ask politely if they could slow down as “you don’t want to miss anything of importance”. Itis worthwhile recording the interview. This allows you to confirm anything which may be unclear from your notes. Don’t try to write every single word ~ concentrate on comprehending what the SME is saying and get the gist of it, rather than trying to record every spoken word. This isn’t possible. If, at least, you are able to note some general point, it will provide the basis for you to ask further questions again. Close the interview ‘Simply advise the SME that you have completed your questioning and you are ready to end the interview. Ask the SME is they have any questions for you. Naturally, you will thank the SME for their time and contribution and offer to send a copy of the final report/paper to them for their interest. PLANNING THE DOCUMENT ‘Once you have gathered all the information you need to write the document, you should plan how it will be written. Some questions to help your planning include: . ‘What information needs to be included so the intended audience can readily use the document? . How will you organise and present the information? . How complex will the language be — technical, non-technical? . ‘What tone is appropriate ~ formal, informal? . What elements will the document contain ~ graphics, tables, index, glossary? . What is its estimated length? . How many graphics will it need? : Most importantly, what timescales are you working to; how long will it take to write, review, print and distribute the document? Draw up a production schedule (sometimes called a milestone chart) that lists each stage of writing and print production to help you plan the document. Make sure the dates are realistic for the project (be prepared for delays at each stage) otherwise the project will appear to be running overtime. The following example is a basic production schedule: a), First draft 10/02/Xx. b) Review 10/03/xX. ©) Second draft 24/03/XX.@) Review uz/ua/xx, €) Final version sent to reviewers 12/04/XX. | _Camera-ready copy (copy ready for print production) sent to printer or production department 30/04/Xx. 8), Printed copies distributed to customers 30/05/XX. Structuring the Document All writing genres require a logical sequence for the reader to make sense of the text. However, technical writing requires more emphasis on format than most because the topic is usually specialised, and the document's sole aim is to impart information to the reader, often in a way that will improve their ability to do something The purpose of the document will help you determine the best structure. For instance, the most logical order for a set of instructions is the order in which the steps are to be carried out. Ina veterinarian’s, report, the best order for presenting the patient’s history might be chronological, but f the report is to inform another veterinarian of the nature of the patient’s condition, the order might start with a summary of symptoms, progress to analysis of tests conducted on the patient, and conclude with a tentative diagnosis, Reports are often structured so that they begin with a brief statement or summary of research findings and conclusions, then state the problem, the research, the analysis of research findings, recommendations and conclusion. Each workplace has its own preferred way of organising documents like reports, and this should be considered when planning the document. The simplest way to plan the structure or order of your document is to write an outline. An outline indicates, often in point form or headings, what content will be included, and in what order. All headings should appear in a complete outline. When preparing an outline, ask yourself if the reader (who could be your employer) will be able to tell from the outline what main and secondary ideas you will present in the document, and in what order you will present them, Write an Outline to Start the First Draft kick-start the first draft by writing an outline following these step: : Write a list of the all the chapter or section headings. Use numbers (|, or 1, 2ete) or capital letters (A, B etc) to indicate their importance : List subheadings or topics under the main headings. Indent these and use lower-case letters (e.g. a, b etc) or numbers (i i etc) to indicate their importance. : Write the first paragraph or first few lines for each heading or for the topic you know most about. This is the start of your first draft. Example of a Standard Outline A. Introduction to the Cut Flower Industry 1. Scope and nature of the industry 2. Types of cut flower producers B. Crop Growth and Selection 1. Growth Factors 2, Plant Variety Rights C. Production Methods 1 Site Selection . Climate . Soils . Water availability . Market proximity 2. Site Preparation3. Propagation . Seeds . Cuttings . Division and other vegetative propagation 4, Crop Production . Fertilising . Pruning . Irrigation . Pest and disease control D. Harvest and Post-Harvest 41. Harvesting techniques 2. Post-harvest storage E, Marketing 1. Domestic markets 2. Global markets F. Conclusion Writing the First Draft Three important things to keep in mind as you write the first draft: Get started and keep going. If you get stuck on something, don’t wait until your mind clears or you find inspiration, or your SME gets back to you with some important information. Move onto another part of the document. You don’t have to write everything in order. Even if you only write a few lines or paragraphs on another section, it’s better than not writing at all. The more you write the less chance you have of stalling and developing writer’s block. It’s okay to include too much information in the first draft. Overwriting in the first draft is less of a problem than failing to include enough information. The most common weakness in technical documents is that they don’t include enough information or explanation, A good edit later will remove extraneous material but leave enough to make It appropriate for the audience and purpose. The first draft is just that, itis not meant to be the finished product. Don’t waste time smoothing and re-writing the text. Concentrate on getting down the facts as accurately and completely as possible. Editing and proofreading should be done after you have completed the first draft. Verify what You Write When you are satisfied the first draft is in workable order (i.e. complete, edited and proofread), prepare hard or electronic copies to send to reviewers. Some points that will help you receive useful feedback from reviewers: Make sure your draft copy is tidy and reads as smoothly as possible. Typos and other errors are a distraction and, faced with a messy draft, many reviewers will assume it is their role to edit the document, rather than checking its technical content. Even though it is a draft copy, aim to present your reviewers with as complete a document as possible (without holding up the production schedule). This means including such things as the table of contents, index, references, graphics and captions.. Indicate clearly the copy is a draft review. Write or stamp the word DRAFT on every page and include a draft or revision number (e.g. First draft or Draft 1.0). Version control is, particularly important when using multiple reviewers and enables you to keep track of, which amendments relate to which version of the draft document. . Use headers and footers to indicate the date, document and section or chapter titles and copyright statement. . On the cover sheet, indicate a return date on which reviewer's comments must be returned to you The most important reviewers will be the SME who provided their technical input. Other reviewers may be collaborative writers, department supervisors, management, and sales or marketing staff. Revise and Amend When you receive a reviewer's feedback, consolidate and analyse their comments, then revise and amend the document accordingly. Depending on the complexity of the project, the review stage may take several weeks or months, and may involve two, three or more document revisions, SET TASK Find a report, a proposal and a manual of your choice. Critically evaluate each in terms of format and structure. Based on your readings so far, note: a). What the writer's purpose seems to be. b] Whois the intended audience? ©) Whether or not the writing is presented in an easy-to-read format. d), Whether or not the writing is structured in a logical format. Take notes. Spend no more than 1 hour on this task