eDocumentation™ ProcessBuild Phase          Knowledge Process, Inc.          www.DocumentationProcess.com          www.KCG...
Table of Contents – Build                                                  Table of Contents – BuildTable of Contents – Bu...
Table of Contents – Build   eDocumentation™ Process phase                       24 Templates and Skeletons ..................
Table of Contents – Build   9. Training, collaboration, and practice                       56    eDocumentation Process ph...
eDocumentation™ Process Flow                               eDocumentation™ Process FlowThe eDocumentation™ Process is a se...
eDocumentation™ Process Flow    Change        The Change phase addresses the process that tracks and updates Policies, Pro...
eDocumentation™ Process FloweDocumentation™ Process phasePlanBuildImplementationChangeVersion 2.0               eDocumenta...
Content Research                                             Content ResearchPolicy, Process, and Procedure research is a ...
Content Research1. Research approachThe research performed by the Documentation developer that is necessary to produce the...
Content Research    •   Are the target users trained in the use of available tools? How competent are the users? For examp...
Content Research    There are also tools that assist in the research task of obtaining the information. Such tools are the...
Content Research4. Prepare for researchTo prepare for research define only the functions that require research. You can al...
Content Research    Attend training sessions    The Documentation developer is a member of the Project team. The Documenta...
Content Research    1. Content to be research    2. Audiences to be participants in content research    3. Research approa...
Content Research        view the Process design. Because the Processes are cross functional, most sessions should be      ...
Content Research        •     Prepare a system flow that guides the screen flow. Validate or complete the flow when the sy...
Collaboration                                               CollaborationCollaboration is the sharing of information. Beca...
CollaborationDevelopmentUsually Policy, Process, and Procedure collaboration occurs at the development level. Project team...
Collaboration    If the portal is only a repository, then it will not serve the collaboration needs. Determine other funct...
Interviews                                                 InterviewsInterviews are an important part of the Research eDoc...
Interviews    Brainstorming can use a strawman to highlight issues or verify solutions, before the actual building of Poli...
Interviews        •     IT / Technical        •     Management        •     Training department        •     Vendors5. Gui...
Interviews    Talk about the real situations    During the interview process, attempt to discuss real situations rather th...
Interviews    Good notes    Take complete, detailed notes, or assign a responsible person to take them for you. Review the...
Templates and Skeletons                                       Templates and SkeletonsA Template is a style guide for docum...
Templates and Skeletons    Repetitive content    Policies, Processes, and Procedures have repeating content in the headers...
Templates and SkeletonsThe following Template has generic headings and text. It is not ‘Fill-in-the-blanks’. When using th...
Templates and Skeletons                                The documentation Template defines the                             ...
Templates and SkeletonsStandard Skeleton HeadingsThe Headings content differentiates a Policy, Process, or Procedure. Sett...
Writing Style                                               Writing StyleWriting Policies, Processes, and Procedures is a ...
Writing Style2. Enterprise writing styleAn enterprise writing style is a combination of accepted rules (for example, gramm...
Writing Style        •     Select specific formats that you will use to emphasize words, phrases, new terms, and examples....
Writing Style                       Usage                              Example                        Explanation         ...
Writing Style5. Parallel structureParallel structure refers to using the same pattern of words, phrases, clauses, and para...
Writing Style                       Usage                                 Correct                             Incorrect   ...
Writing Style                       Usage                               Correct                          Incorrect        ...
Writing Style7. Capitalization and numbers    The writing standards for capitalization and numbers are set by the enterpri...
Writing Style    encountered when writing Policies, Processes, and Procedures. They are presented here only to save you   ...
Writing Style    Semicolons                       Usage                               Correct                             ...
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
3. eDocumentation Process Build Phase
Upcoming SlideShare
Loading in...5
×

3. eDocumentation Process Build Phase

1,172

Published on

Published in: Business, Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,172
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
0
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Transcript of "3. eDocumentation Process Build Phase"

  1. 1. eDocumentation™ ProcessBuild Phase Knowledge Process, Inc. www.DocumentationProcess.com www.KCGGroup.com
  2. 2. Table of Contents – Build Table of Contents – BuildTable of Contents – Build ...................................................................................................................... 2 eDocumentation™ Process Flow .......................................................................................................... 5  eDocumentation™ Process phases 5  eDocumentation™ Process phase 7 Content Research ................................................................................................................................... 8  Connecting the Dots 8  1. Research approach 9  2. Research audience 9  3. Research methods and tools 9  4. Prepare for research 12  5. Prepare Research plan 13  6. Perform research 14  7. Research and test 16  eDocumentation™ Process phase 16 Collaboration ......................................................................................................................................... 17  Types of collaboration17  Development 18  Changes 18  Usability 18  Methods 18  Getting everyone on board 19  eDocumentation™ Process phase 19 Interviews .............................................................................................................................................. 20  1. New development 20  2. Nonlinear task 20  3. Types of interviews 20  4. Who to interview 21  5. Guidelines for interviews 22  6. Conducting interviews 23  7. Interview approach 24 Version 2.0 eDocumentation™ Build Phase Page 2 of 73
  3. 3. Table of Contents – Build eDocumentation™ Process phase 24 Templates and Skeletons ..................................................................................................................... 25  Template controls 25  Template design 25  Document Skeleton 26  Standard Skeleton Headings 29  eDocumentation™ Process phase 29 Writing Style .......................................................................................................................................... 30  1. Public writing style books 30  2. Enterprise writing style 31  3. Headings, paragraphs, sentences, lists, and tables 31  4. Sentence construction 32  5. Parallel structure 34  6. Lists 35  7. Capitalization and numbers 37  8. Punctuation 37  9. Abbreviations 39  10. Examples 40  11. Slash marks 40  12. Text and usage 40  13. Graphical User Interfaces 41  14. Format 42  15. Autocorrect tools 42  16. Consistent terms 42  eDocumentation™ Process phase 42 Modular Writing .................................................................................................................................... 43  1. Components 45  2. Content modules 46  3. Content usage 47  4. Basic guidelines 47  5. Policy module guidelines 48  6. Process module guidelines 48  7. Procedure module guidelines 50  8. Identifying modules 56 Version 2.0 eDocumentation™ Build Phase Page 3 of 73
  4. 4. Table of Contents – Build 9. Training, collaboration, and practice 56  eDocumentation Process phase 56 Headings................................................................................................................................................ 58  Function 58  Guidelines 60  eDocumentation™ Process phase 61 Writing Overviews ................................................................................................................................ 62  Modular overviews 62  Examples 62  eDocumentation™ Process phase 63 Testing Policies, Processes, and Procedures ................................................................................... 64  Objective 64  1. Types of testing 64  2. System testing 65  3. Testing methods 66  4. Test and verification steps 67  5. Test system requirements 68  eDocumentation™ Process phase 70 Issue Reporting ..................................................................................................................................... 71  Issue report 71  Issue review and resolution 71  Escalation process 72  eDocumentation™ Process phase 72 Version 2.0 eDocumentation™ Build Phase Page 4 of 73
  5. 5. eDocumentation™ Process Flow eDocumentation™ Process FlowThe eDocumentation™ Process is a set of guidelines, not decrees, that guide the Documentation developerthrough the research, development, and implementation of Policies, Processes, and Procedures. The objective isto create and produce Policies, Processes, and Procedures that are clear, concise, complete, and correct™.Although the Process is a somewhat sequential Process, each phase touches the other phases and relies on thediligence and quality of the previous phases. Previous phases may be revisited, and if conditions warrant,modifications may be made to previous assumptions and decisions.eDocumentation™ Process phasesThere are four major phases that comprise the eDocumentation™ Process. The phases encompass the tasksthat need to be reviewed and performed as the project progresses, depending upon the company, project, andscope. Plan The Plan phase incorporates the tasks that are required to ensure that the project is properly scoped with the correct focus, level of detail, team members, and proper content. Planning does not make a project longer or more complicated, but ensures that erroneous assumptions do not become part of the project approach and plan. Policies, Processes, and Procedures are usually dependent upon other resources; therefore, it is important that all the puzzle pieces fit. Build The Build phase researches and develops the Policies, Processes, and Procedures. Based on the decisions from the Plan phase, the Policies, Processes, and Procedures are researched, written, verified, and tested. This phase is often looked upon as ‘just writing’. However, there are other critical tasks that are performed in addition to writing. Implement The Implement phase rolls out the Policies, Processes, and Procedures to all the users. A Policies, Processes, and Procedures project is never complete until the users are trained. This is often an overlooked task, but it is – without a doubt – key to the success of the overall project. The Implement phase incorporates appropriate change management principles.Version 2.0 eDocumentation™ Build Phase Page 5 of 73
  6. 6. eDocumentation™ Process Flow Change The Change phase addresses the process that tracks and updates Policies, Processes, and Procedures. Change is the nature of Policies, Processes, and Procedures. Updates are often overlooked, and at that point the Policies, Processes, and Procedures become outdated and less reliable. Therefore, guidelines and Processes are introduced to assist with keeping Policies, Processes, and Procedures current.Version 2.0 eDocumentation™ Build Phase Page 6 of 73
  7. 7. eDocumentation™ Process FloweDocumentation™ Process phasePlanBuildImplementationChangeVersion 2.0 eDocumentation™ Build Phase Page 7 of 73
  8. 8. Content Research Content ResearchPolicy, Process, and Procedure research is a Process carried out before any significant writing is performed.Based on the project, research can also be conducted at any point, including the testing and implementationphases. Content research is the task of conducting a thorough and comprehensive study of the subject matterthat will become the content for the Policies, Processes, and Procedures. The amount of research required isbased on the size, scope, and complexity of the project. Research requires organization and planning;otherwise the collection and compilation of information can become unwieldy.The documentation is the end result, to a greater or lesser degree, of research that has been performed byanalysts, designers, managers, or executives. However, the research previously performed will not include all theinformation that will be required by the Documentation developer. The Documentation developer’s task is tocompile the information into Policies, Processes, and Procedures that are clear, concise, complete, and correct™.In the simplest explanation, the Documentation developer is ‘connecting the dots’ for the user. When ‘connectingthe dots’, information that will be required by the users may be missing or tasks not fully defined. Therefore, theDocumentation developer is looking for the gaps in the previous research. There will certainly be gaps, as theresearch is usually not performed to the level of detail required by users. Connecting the Dots Preliminary research for Detailed research Policies, Processes, and for Policies, Procedures Processes, and Procedures Policies, Processes, and Procedures developed with specific content for a specific audienceVersion 2.0 eDocumentation™ Build Phase Page 8 of 73
  9. 9. Content Research1. Research approachThe research performed by the Documentation developer that is necessary to produce the users’ Policies,Processes, and Procedures involves study, investigation, clarification, understanding, and compilation.Begin the research with the information obtained from tasks performed during the eDocumentation™ Planningphase. If the project did not have a Planning phase, research preparation steps will be required.To understand the dynamics of the project you are undertaking, consider the following to assist with your researchapproach: • Determine if research has been performed that outlines the new Policies, Processes, and Procedures. If so, the Documentation developer is not ‘starting-from-scratch’, but compiling the information into a usable form. • Determine if there is extensive new Policy. The Documentation developer does not establish Policy. The Documentation developer reviews Policy to determine if the Processes and Procedures adhere to Policy. As Policy becomes more complex and specialized, the Documentation developer must work very closely with those who have an in-depth knowledge. In addition, the Policy will drive the new user Processes and new user Procedures. • Determine if the enterprise is implementing a new strategic plan for the organization. If so, systems and Processes will be selected to support the strategy. The organization will change to implement the new systems and Processes. In this case, the Documentation developer will work in concert with the organization to define and document the new Policies, Processes, and Procedures. • Determine the level of knowledge that exists among subject matter experts for the new Policies, Processes, and Procedures. Is the information fragmented between many resources, or does a specific group have a complete understanding of the knowledge required for the Policies, Processes, and Procedures? • Determine if you are updating only existing Processes and Procedures, which may have been changed, but the documentation was not updated and properly implemented. This situation requires the Documentation developer, with the management, to research and determine the specific Processes and Procedures to ensure that the correct Procedures are performed throughout the enterprise or department.2. Research audienceThe Documentation developer uses the eDocumentation™ Audience Evaluation as a beginning for research.However, there will be additional contacts for research – vendors, users, subject matter experts, management.The method must match the audience. For example, a questionnaire may not be the best method formanagement, but may be effective for users.3. Research methods and toolsDuring the research task, content is gathered that will become the Policies, Processes, and Procedures. • The Method is how to accomplish the research. • The Tools are what is used to perform the research.Therefore, methods and tools go hand-in-hand. They will be mixed-and-matched to produce the best results foryour enterprise or department. Evaluate the available methods and tools and determine the most effective way toattain the needed information from users and Project team members. Using the Audience Evaluation, considerthe following questions for each audience, when selecting research methods and tools:Version 2.0 eDocumentation™ Build Phase Page 9 of 73
  10. 10. Content Research • Are the target users trained in the use of available tools? How competent are the users? For example, are the users educated to use a workspace to discuss a document or set of documents? • Are the users comfortable using the tools and methods? • Will the users actually use the tools? • What tools will be used for each method? • Will the methods get the proper information? • What additional methods need to be used? • Will the users complete questionnaires, participate in meetings, feel comfortable giving you their existing documentation? Methods The Documentation developer will use a combination of methods. For example, a questionnaire can be used to quickly collect general information from many users in multiple locations. Interviews can be used for more detailed information from a smaller group. • Warroom • Written questionnaires and surveys • Focus groups or small group meetings • Individual face-to-face meetings • Web based or public sources • Hands-on • Walk-thrus Tools Based upon the audience, methods, and subject matter being researched, select the proper tool to use to gather the content. Tools must be appropriate for the method. For example, designing a Process flow on a conference call may not be highly effective. Use of an online meeting tool during the conference call may greatly enhance the method. • Collaboration tools (for example, Sharepoint™) • Document workspaces • Teleconferencing • Web conferencing and webinars (for example, Webex™) • Online and/or web meeting tools • Company portals and web sitesVersion 2.0 eDocumentation™ Build Phase Page 10 of 73
  11. 11. Content Research There are also tools that assist in the research task of obtaining the information. Such tools are the following: • Process and functional mapping • Cause Effect diagrams • Suppliers Inputs Process Outputs Customers Requirements (SIPOC) • Plan Do Check Act (PDCA) • Data evaluation • Systems The content to be researched and the audiences it addresses drive the methods and tools used for research. An approach is defined for the content, audience, methods, and tools. There is a back-and-forth between the available methods and tools and the approach, with the objective being to conduct research in the most effective and efficient manner. If certain approaches are not working for your audience, change it.Version 2.0 eDocumentation™ Build Phase Page 11 of 73
  12. 12. Content Research4. Prepare for researchTo prepare for research define only the functions that require research. You can always expand your research,as needed. Gather all existing relevant materials, which can include the following: existing Policies, Processes,and Procedures; vendor documentation; project notes; and documentation prepared by project members. Duringthe Planning phase much of this material may have been compiled. Organize existing documentation After gathering existing documentation, organize the documents for ready reference based upon the need. Documents can be arranged by topic, date, category, or subject matter experts. Obtain the electronic copies, if available. Categorize the gathered information for future reference and access during the eDocumentation™ Development task. Category Type of Information Policies, Processes, and Procedures Policies manuals Procedures manuals Work instructions Process maps Process flow charts Systems Screens in the computer project Reports in the computer project Computer system flows Copy of conversion plans Copy of implementation plan Management Dictionary Schedule Management plan for related subject Organizational chart Test Test plans Test scenarios Training Training program for related area Audience evaluations Training schedules Review existing documentation Determine the value of existing documentation. • Determine if there is anything of value that can be used as source material for the new Policies, Processes, and Procedures. Perhaps minor revisions are needed or reformatting is required. • Determine if there are noticeable gaps in the existing documentation. For example, are there no Policies or controls that drive the Processes and Procedures? Are there no Process maps? • Determine if the existing documentation consists mainly of generic vendor documentation.Version 2.0 eDocumentation™ Build Phase Page 12 of 73
  13. 13. Content Research Attend training sessions The Documentation developer is a member of the Project team. The Documentation developer should attend Project team training sessions and be a part of any training that may be beneficial in the following ways: • Enhance their knowledge of systems and Processes that will be implemented. • Enhance their knowledge of systems and Processes that will require supporting Procedures. • Participate in discussions of any topic that is related to the Policies, Processes, and Procedures. Attend design and requirements meetings The Documentation developer should be present at design and requirements meetings, especially if the project is a large scale development project. Since it is not possible for the Documentation developer to attend all meetings, an attempt should be made to attend meetings that pertain to the documentation that is being researched. The Documentation developer has an essential role on the project. The meetings determine the following research to perform: • Understand and identify major functions and requirements. • Understand and identify cross functional aspects of the project. • Understand and identify potential control issues. Understand and identify potential issues. Identify new Policies, Processes, and Procedures. Identify subject matter experts and individuals that support the experts.5. Prepare Research planUse the information from the eDocumentation™ Planning phase. • Project scope • Audience evaluation • Working team • Review team • Project team • Content audit and evaluationFrom the preliminary research steps, use the information obtained from the following research tasks: • Existing documentation • Research methods • Training sessions • Design and requirements meetingsBased upon the information you have gathered, a research plan or matrix is prepared that indicates the following:Version 2.0 eDocumentation™ Build Phase Page 13 of 73
  14. 14. Content Research 1. Content to be research 2. Audiences to be participants in content research 3. Research approach and methods to be used for each audience 4. Research tools to be used with the research method for each audience 5. Evaluation to determine if information gathered is sufficientThe Research plan is published to establish who and what is involved during the research phase. Comments andchanges should be welcomed. It is important to obtain as much information as possible at the beginning of theproject.6. Perform research Policy research Because Policies are the laws, guidelines, and guiding principles of an enterprise, business unit, or department, they must be developed in conjunction with the Policy owner. A Documentation developer cannot establish and/or create Policy. However, the Documentation developer can work with the Policy owner on all other aspects of Policy development - consistency, usability, training, etc. The Policy owner is totally responsible for the content. Enterprise policies Enterprise Policy content is created by the subject matter expert. Because this level of Policy affects the enterprise, it must be absolutely correct in the intent and direction. Therefore, enterprise Policy must be created by the owner and supported by the subject matter experts. The subject matter experts may range from executives to outside legal counsels. If Policy is developed by an outside consultant or group, the Policy development must be carefully crafted to reflect the enterprise requirements. The Documentation developer will work mainly as a facilitator to implement the documentation standards. Department policies Department Policy content can be created by various people – management, subject matter experts. The degree of support required for Policies will vary, based on the background and experience of the Documentation developer. Because the scope of a department Policy is limited, the Documentation developer, with guidance, may be able to develop the Policy. However, the Policy must be verified by management to ensure that the Policy is correct. Process research Processes developed for purposes such as reengineering are usually not suitable for users. User Processes should contain information that is needed by them - not for technical or analytical reasons. Processes must adhere to all applicable Policy. Therefore, it is helpful if the Policy is available for research meetings. If Policy is being developed, the research may be unstable until Policy is finalized and approved. Enterprise Processes Enterprise Processes are high level. The research determines the level of detail for the Process flows. They are cross functional. A warroom is an effective and efficient method to start the Process and get all the functional owners and representatives coordinated and in agreement. A large area should be used, where all participants canVersion 2.0 eDocumentation™ Build Phase Page 14 of 73
  15. 15. Content Research view the Process design. Because the Processes are cross functional, most sessions should be conducted with a varied group of representatives, as changes may affect other areas. Functional Processes Functional Processes can range from complex cross functional Processes to simple task oriented Processes. The size and scope of the Process will determine the methods and tools used. The effectiveness of warrooms and focus groups is based on the number of participants and their knowledge. Follow up is usually conducted with face-to-face meetings for details and questions. Differences between functional groups Inevitably there will be differences concerning how a Process actually works, especially if the Process has never been documented. Therefore, Process research may require as-is Process flows be defined before to-be Process flows can be defined. The as-is Process Set determines the baseline and allows enhancements and efficiencies to be developed. Procedure research Procedure research encompasses any subject that requires step-by-step instructions, whether it is a report, system, or detailed Process. Procedure research requires the tools (for example, system, reports) that the user will use to perform the Procedure. Tasks Task research begins with knowing and understanding the applicable Process and Policy. If a Process map is available, you will use the map as a starting point for the research. The value of the Process map will depend upon the complexity and correctness of the Process map. To understand a complete task, perform the following: 1. Review the Process map, if available. 2. Select a task that will become a Procedure. Select the task that starts the Process and is within your area of responsibility. 3. Prepare an outline of the task. Do not attempt to capture minutia at this point in the research. 4. Determine if the task is cross functional. 5. Determine the components used by the task (for example, systems, reports, etc.) 6. Determine the level of detail required for the task, based on the eDocumentation™ Audience Evaluation. 7. Determine the steps performed within the task. The task will be reviewed to determine if it is stand-alone. If the research demonstrates that there are multiple tasks, the Documentation Developer will break down the original task into multiple Procedures. Refer to the eDocumentation™ Process Modular Writing chapter. Systems Systems research will reveal the degree to which the system guides and imposes Policies and Processes. If the system guides and imposes the Policy, the documentation is simpler, because the instructions that impose the Policy and Processes will not be as extensive. How intuitive the system is for the users is another consideration; some systems are complex and can be confusing. The following are basic steps to research a system. The research may be able to serve as a rough draft for the Procedure.Version 2.0 eDocumentation™ Build Phase Page 15 of 73
  16. 16. Content Research • Prepare a system flow that guides the screen flow. Validate or complete the flow when the system is thoroughly researched. • Conduct a screen-by-screen system ‘walk thru’ based on a business Process. Make rough screen prints. Add basic notes under the screen prints. This is also a very fast and easy way to create ‘rough’ documentation, if the data on the screens is sufficient and correct. If you cannot do this, the Documentation developer will have to recapture the screens with the proper tools. • Understand the screen functions thoroughly. If you do not, there is probably a step that is missing. • Obtain security to access the system, if possible. If you are not able to access the system, you will then have to contact the expert every time you have a question. It is far more efficient to have access to the system, so that you can answer your own questions. • Review existing training programs to determine if applicable information is contained.7. Research and testProcess and Procedure research requires ‘hands on’ methods - especially testing and verification. Because thedocumentation is the ‘how to’, the Documentation developer must be certain the Process and the Procedure arecorrect - no missing or extraneous information which will cause incorrect results and confusion.Arrange to be part of testing - specifically the conference room pilot (CRP) and the user acceptance testing.Although these tasks are performed at the end of a project they are, nevertheless, a research function; newinformation always surfaces.Testing may be the first opportunity the Documentation developers, who become involved in the project ‘later inthe game’, have to observe and analyze the system and Processes in detail. In that case, being involved withtesting the Policies, Processes, and Procedures becomes a required task for the Documentation developer.Documentation developer identifies the following from the testing: • Scenarios that can be converted to Procedures • Policy requirements or revisions • Additional detail or views of ProcessIt must be emphasized that during testing there may be excellent scenarios prepared by the subject matterexperts. The scenarios can ‘almost’ be converted directly into Processes and Procedures. Of course, this willvary with project and subject matter experts, as their expertise will vary.eDocumentation™ Process phaseBuildVersion 2.0 eDocumentation™ Build Phase Page 16 of 73
  17. 17. Collaboration CollaborationCollaboration is the sharing of information. Because Policies, Processes, and Procedures require the knowledgeof many people, it is imperative that there be a high level of collaboration. The subject of collaboration can bevery broad and, at times, general. The collaboration process can be structured or unstructured. We are onlyaddressing methods that can be effective in sharing and managing information during the development andmaintenance of Policies, Processes, and Procedures.Types of collaborationIn order for Policies, Processes, and Procedures to retain the status of clear, concise, complete, and correct™, amethod for users to collaborate with the Documentation developers is required. Examples of neededcollaboration are listed: • Additional content for clarity • Process to determine cross-functional impact of changes • Recommended changes related to usability issues • Training needs • Feedback for errors or incomplete contentContent is researched, categorized, and developed into a document that is reviewed, approved, revised,published, trained, and maintained. The cycle then starts again. During the process users, subject matterexperts, technical resources, and management give their input – changes, deletions, suggestions. This is a verydynamic process. If collaboration processes are not managed, it becomes confusing and the resulting Policies,Processes, and Procedures are not clear, concise, complete, and correct™.Version 2.0 eDocumentation™ Build Phase Page 17 of 73
  18. 18. CollaborationDevelopmentUsually Policy, Process, and Procedure collaboration occurs at the development level. Project teams are formedand some framework for collaboration is established; this is part of project management. However, Policy,Process, and Procedure development requires its own approach. • Meet with users and subject matter experts that may be in multiple locations • Control and monitor inflow of information relating to new content • Perform intensive content reviews • Control and monitor approval reviews • Control and monitor issues and problems related to documentationIf you attempt to implement and use collaboration software, be aware that you will need to create and foster aknowledge culture in order for team members to be willing to use the tool. In essence, this is creating a newproject that will require implementation, training, and support. Some enterprises may have the collaborationsoftware, but the software may not be widely available to all projects. However, you can still use collaborationprinciples and concepts; however, that will take more effort. We are referring, not to where the Policies,Processes, and Procedures are stored, but to the collaboration efforts required to control the development of thedocumentation. For example, your company may have a portal where published documents are accessible.However, the previous steps are not managed by the portal.ChangesThe reporting and feedback from users is usually less after implementation. Unless there is a documentationfeedback system, there is will be no way – other than email – to report problems. The Policies, Processes, andProcedures can easily become out-of-date and thus, not clear, not concise, not complete, and not correct.Setting up a web-based issue reporting process allows users to records their issues and feedback. The issuesare consolidated, and documentation issues can be immediately changed – if required – or incorporated in thenext scheduled review.UsabilityFeedback of usability factors should be promoted. Testing usability factors does not replace workplace use andreference of Policies, Processes, and Procedures. Setting up a web-based issue reporting process wouldaccommodate usability feedback.MethodsThere are a number of methods available for collaboration. Determine if your company has collaboration softwareor processes that would be available to your project. If none are available, you will need to develop andimplement solutions. Enterprise portal Most enterprises have an enterprise portal. Whether enterprise-wide Policies, Processes, and Procedures are published to the portal should be determined. If they are, every user of Policies, Processes, and Procedures must be able to use the portal.Version 2.0 eDocumentation™ Build Phase Page 18 of 73
  19. 19. Collaboration If the portal is only a repository, then it will not serve the collaboration needs. Determine other functionality that is or would be available on the portal. SharePoint Team Services ™ SharePoint Team Services is an example of a collaboration tool. The SharePoint Team Services provides tools for the following: • Issue reporting and other list capabilities • Elementary document version control • Basic check in and check out capabilities • Document work spaces for collaboration • Elementary workflow SharePoint Team Services is very easy to set up and can be dedicated to a single project. Because it is web based, it is available for all to access and use. However, there are implementation and training issues associated with Team Services. To be effective, all team members must have access and use of the site. Email Email is not an effective method for collaboration. Its only purpose is distributing documents and receiving comments or changed documents. However, the management of copies and revisions is cumbersome and time consuming. Authoring software Authoring software has revision and comments functionality. Some software revision functions can be difficult to manage, if different users have conflicting revisions. This results in the Documentation developer having to negotiate the correct content. However, the revision and comments functionality does serve to record who made the changes. Shared folders Some may view that storing the Policies, Processes, and Procedures on a shared drive and a shared folder serves as a vehicle for collaboration. This is not the case. While users and team members may have access to the Policies, Processes, and Procedures, they do not have a method to share information, outside of the traditional email.Getting everyone on boardSetting up a knowledge and collaboration culture is not a small task. Getting everyone on board can add time toa project.eDocumentation™ Process phaseBuildVersion 2.0 eDocumentation™ Build Phase Page 19 of 73
  20. 20. Interviews InterviewsInterviews are an important part of the Research eDocumentation™ phase. When researching content for thedevelopment of Policies, Processes, and Procedures, it is necessary to interview people who have a thoroughknowledge of the subject matter. Based upon the interviews, the Policies, Processes, and Procedures aredeveloped.Starting the interview process can be overwhelming. Depending upon the scope of the project, the processrequires coordination and planning between those conducting the interviews. Interviewees can become quiteupset if they are asked the same questions by multiple people. Therefore, this phase requires planning in orderfor the interviews to be effective and efficient.1. New developmentOn new development and larger projects, training may be conducted for the project and the user team. Inaddition, there are design meetings and reviews that can give Documentation developers required backgroundand knowledge. At times the project leaders may be hesitant to allow Documentation developers to attend keyplanning meetings. This is a mistake. The Documentation developers communicate the required informationand, therefore, must completely understand the information. It is time well spent to include Documentationdevelopers. The knowledge gained from the users, the subject matter experts, and the project team is vital topreparing Policies, Processes, and Procedures. Including all involved people in the beginning of the planningphase puts everyone on the same page and, in the end, is profitable.2. Nonlinear taskThe interview tasks are not linear. Most project plans have a set timeframe to gather requirements and developthe resulting Policies, Processes, and Procedures. However, during the development process, many questionsarise that require clarification. The Documentation developer must build time into the schedule for reviews andfollow-up.3. Types of interviewsThere are different methods for conducting interviews. Determine the type of interview to conduct, based on thephase of the project, type of information required, the group to be interviewed, and the required outcome. Thefollowing are some types of interviews: Warroom A warroom is conducted during the planning phase and follows the kickoff meeting. A warroom is a strategic planning process. A group of people that is associated by a Process or function organizes the project and plans the basic strategy and scope. Because the group is never more than 10 people, there can be multiple groups. The warroom will raise many issues that will directly affect the Policies, Processes, and Procedures and therefore, the author. An issues log is compiled and tracked to resolve those issues that affect the Policies, Processes, and Procedures. Brainstorming sessions Brainstorming is a method used to gather information and resolve issues. Brainstorming is very effective during meetings where a problem is discussed and a solution has not been determined. Brainstorming sessions have a completely different dynamic than other interviews. The process is more informal and open, which leads to good discussions before final decisions are made.Version 2.0 eDocumentation™ Build Phase Page 20 of 73
  21. 21. Interviews Brainstorming can use a strawman to highlight issues or verify solutions, before the actual building of Policies, Processes, and Procedures. Job observation Observation of users, performing their job functions, is used to gain an overview of the Process. It is usually performed before detailed interviews are conducted. Some of the uses for job observation are as follows: • Establishes a basic outline of the job function and the tools used. • Highlights job inefficiencies. • Verifies policy compliance. • Researches and verifies process flows and procedures. One-on-one One-on-one interviews are conducted with individuals to determine the details of their job function or their part of a Process. This type of interview is conducted with users, subject matter experts, management, technical personnel, or whoever is needed to gather content. As research and development of the Policies, Processes, and Procedures progresses, this type of interview is conducted to answer questions that will arise. One-on-one interviews can be formal meetings, a simple phone call, or an email. The objective, when conducting this type of interview, is to be prepared and have all the information needed at hand, so that questions can be properly framed. Group interviews Group interviews are conducted when a subject crosses job functions or Processes. If a decision cannot be determined by a single person or the subject affects multiple areas, always conduct a group interview. Because it is difficult to update an individual with multiple one-on-one meetings, a group meeting assures that essential people are involved. Be prepared and have all the needed information available. The issue can then be properly framed and the proper solution agreed upon.4. Who to interviewYou should cast a wide net in determining who to interview. The most successful projects encourage theDocumentation developers to interview whomever they think they need. This approach can be abused, if authorshave not planned and are not fully prepared for their interviews. A user should not be asked the same questionsby multiple Documentation developers.If the Documentation developers are in a centralized department or on a large project, there is usually a hierarchyof who is allowed to talk to users and others. This is understandable. However, the Policies, Processes, andProcedures integrity requires that Documentation developers not be reduced to clerks. The more layers of peoplethat are between the information sources and the Documentation developer, the more the Policies, Processes,and Procedures will be degraded.Depending upon the project, the groups of people to be interviewed may include the following: • Content management / Taxonomy • Content review team • Current and new users • Audiences representativesVersion 2.0 eDocumentation™ Build Phase Page 21 of 73
  22. 22. Interviews • IT / Technical • Management • Training department • Vendors5. Guidelines for interviewsPreparations that promote successful interviews are as follows: Be prepared • Determine the purpose and objective of the interview. • Prepare an agenda for the interview. Distribute the agenda so that all attendees can be prepared. • Determine if the user is aware of why you have requested an interview. Depending upon the project communication, they may not be aware of why you are asking for the interview. Therefore, an introduction will be necessary. • Prior to the meeting, send the user a list of information that needs to be available. This may include reports, existing Policies, Processes and Procedures, or existing notes. This will give the user an opportunity to think about the interview. • Prepare a list of questions to ask that will accomplish that purpose. The questions will guide the meeting and keep it focused. • Compile a list of issues that arise for followup or that require an interview with another person. Keep the meeting within a set timeframe. • Follow up the interview with an email thanking the user for their time and information. Recap the meeting and any action items that were identified. Give the user your information and encourage them to contact you, if they have any questions or think of additional information that you should have. Determine attendees Determining who should attend an interview meeting requires knowing the purpose and objective of the interview. You will not know who should attend, if you do not know what is being discussed. When you have determined the purpose and the objective, determine the groups based on the following: • What level of detail will be discussed? • What functional areas touch or interact with the content at that level? • Who are the key people that represent the areas? • Who are the key people who use the content from those areas? When the interview groups have been defined, give the list a reality check to determine if others need to be added or removed.Version 2.0 eDocumentation™ Build Phase Page 22 of 73
  23. 23. Interviews Talk about the real situations During the interview process, attempt to discuss real situations rather than theoretical situations. This enables the users to have more reality on the subject being discussed. However, if the new system or Process will cause major changes, relate the changes to current situations, and describe how they will change. This may require a bit of orientation as to why a change is required. Never a dumb question The topic about which the author is writing must be completely understood. Therefore, for both the Documentation developer and user, there is no such thing as a dumb question. Of course, this is assuming that the Documentation developer and user are professionals. Some users can be difficult and do not like to answer questions. When this arises you may need to find another user that is more willing, or have management determine what is causing the problem.6. Conducting interviews Be positive Do not talk about the problems that the new implementation is encountering; all implementations have problems. On the other hand, don’t be a Pollyanna; you will not be taken seriously. You must be honest and interested in what the user is telling you. Note any concerns so that they can be taken up with the proper people. Concerns may uncover potential issues. Acknowledge any concern and let them know that it will be addressed. Establish a trust Listen to user responses; do not judge what they are doing. Remember, you are there to gather information – not judge how users are doing their jobs or evaluate their job performance. You will find, with this method, your users will then come to you and originate issues. This is the foundation for good user relations. Conduct stress-free interviews Conducting interviews that are friendly and open to communication brings out the best of people. Some users are very reticent about speaking in an interview. Interviews that are confrontational and argumentative will accomplish little. Requests for future interviews will be resisted, and the interview process will be greatly hampered. When there are those that are confrontational and argumentative, conduct those interviews separately. Control the atmosphere of your interviews. Interview several people Interviewing several people together promotes conversation. However, make sure you do not have incompatible people in the meeting, where one person (for example, a manager and a worker) causes the other one to shut down. Get facilitation training If you are reticent and have problems conducting interviews, get facilitation training (reference a book or web based course) to assist in asking questions and controlling the interview meetings. You must feel comfortable that you are able to conduct positive interviews. Proper reference materials Have the proper reference materials available during the interview. Being able to refer to actual materials will add context, when needed. Use a projector liberally to reference screens or to walkthru a process; it focuses a person’s attention and will answer certain questions directly.Version 2.0 eDocumentation™ Build Phase Page 23 of 73
  24. 24. Interviews Good notes Take complete, detailed notes, or assign a responsible person to take them for you. Review the notes within eight hours of the meeting to ensure that issues and situations are not missed and then forgotten. Distribute the notes, as required for review and changes.7. Interview approachThe following is a brief approach to conducting interviews. Answering these questions will provide basic interviewpreparation. • What is the purpose for the interviews? Data gathering Data verification • Are there existing Policies, Processes, and Procedures for the subject matter? • What subjects need research? • What type of documentation is being prepared for the subject? • Who are the subject matter experts? • What is key related information? • What types of interviews will be conducted? • What interview technique will be used? • Who will conduct the interviews?eDocumentation™ Process phaseBuildVersion 2.0 eDocumentation™ Build Phase Page 24 of 73
  25. 25. Templates and Skeletons Templates and SkeletonsA Template is a style guide for documents. Templates enable all Policies, Processes, and Procedures to beconsistent in format and appearance. This consistency is an enormous benefit for the users. They do not have touse documents that are difficult to read, because of the format, or adapt to different formats for different Policies,Processes, and Procedures. In essence, the Template is the rule that is set for formatting a document. TheDocumentation developer is able to concentrate on creating the content for the document and not on formattingthe document.A Template has built-in functionality, which can include predetermined styles, formatting, boilerplate text, auto textentries, macros, custom toolbars, and shortcut keystrokes embedded in the Template.Template controlsThe ability to change a Template by the individual authors varies, depending upon the authoring software. Somesoftware has stringent controls, whereby the author cannot change the Template. Other software allows allauthors to create or change a Template, making it very difficult to maintain a consistent Template and, therefore,consistent documents. Templates that have lax controls require documents to attach the proper Template as afinal step. Although this may be viewed as ‘extra work’, in the long view it will save time.Template designA Template defines the look and feel of a document. Every document has a single Template ‘attached’ to it.Therefore, usability issues are a major factor when designing a Template. Multiple Templates may be requiredfor the different types of documents within a document set. The following are the basic Template components: Page layout The page layout defines the page margins, paper size, and page orientation. It is the basic definition of the page. Styles Styles are the foundation of a Template. A style is the formatting and attributes for a paragraph or a character. A style is attached to a Template and also to the document; most authors are familiar with the ‘normal’ paragraph style. Predefined styles have built-in formatting: however, the built-in formatting can be customized. To ensure consistent formatting between documents that use different Templates, styles with the same name must have the same format attributes. Never manually format a paragraph or character. Always set up paragraph styles and attach the styles to a Template. The following are the basic formatting options for a style: What are the font style, size, and color? What is the indentation? Do not use the tab character to indent; always define the amount of indentation for the paragraph. It is difficult to maintain a document when tab characters are used for indentations. What is the space above and below the paragraph? The paragraph character should never be used for spacing. Define the spacing for a paragraph by defining the space above and the space below the paragraph. Macros Macros can be created for a specific Template. Repetitive actions or key strokes are easily accomplished with a macro, saving time and aiding consistency.Version 2.0 eDocumentation™ Build Phase Page 25 of 73
  26. 26. Templates and Skeletons Repetitive content Policies, Processes, and Procedures have repeating content in the headers, footers, headings, titles, and properties. In addition, instructions that assist the author with creating their document can also be included. Toolbars Toolbars can be customized for a Template to display those functions that are routinely used and removing those that are not used. Tool bars can be an important aid to the author’s productivity. Graphic software Graphic software (Visio®, SnagIt®) should have standard and consistent Templates. Graphics require consistency in color, line width, line style, fonts, and text size. The look and feel of the graphics should be consistent with the actual documents.Document SkeletonRelated documents or a document set (Policies, Processes, Procedures, Quick Reference Guides, ScreenInstructions, and Report Instructions) will have different types of content and different information layouts.However, they do not necessarily require separate Templates. A single Template can be used for differentcontent purposes and format layouts.The eDocumentation™ Process uses the term ‘Skeleton’ to describe a document that is used for a specificdocument type (Policy, Process, or Procedure), but is based on a single Template. It contains the preset contentfor that specific type of document (for example, a Policy document or a Procedure document), but the formattingis based on a single and shared Template. Therefore, a document set - Policies, Processes, and Procedures - isbased on a single and shared Template.Skeleton documents are meant to be ‘Fill in the blanks’ rather than ‘Start from scratch’. The subject matterexperts can complete the content without having to deal with the complexities of Templates. As a note, a majoradvantage in using Skeletons is that the content of the Policies, Processes, and Procedures is not interchangedand combined into a single document. This enables using modular writing.Version 2.0 eDocumentation™ Build Phase Page 26 of 73
  27. 27. Templates and SkeletonsThe following Template has generic headings and text. It is not ‘Fill-in-the-blanks’. When using the Skeletons,the user is guided to complete the document.The following example illustrates a Template and the resulting three Skeletons that are created for the specificdocument type of Policy, Process, and Procedure. Set up Page Margins Page Orientation Layout Define Styles Title Font Template Paragraph Heading Define Tables Definition Body Text Set up Macros Footer Use a single Template Same Template - Different Content Types Section x Section x Section x Policy Process Procedure Legal Reference Process Scope Screen Instructions xxxx xxxx xxxx Page x of x Page x of x Page x of xVersion 2.0 eDocumentation™ Build Phase Page 27 of 73
  28. 28. Templates and Skeletons The documentation Template defines the page layout, styles, and more. The subsequent three Skeletons add content and guidelines for Policies, Processes, and Procedures.Version 2.0 eDocumentation™ Build Phase Page 28 of 73
  29. 29. Templates and SkeletonsStandard Skeleton HeadingsThe Headings content differentiates a Policy, Process, or Procedure. Setting up predefined Headings in aSkeleton guides the authors and Documentation developers, when developing the documents. For example, aPolicy will not have system instructions or report instructions. As a guideline, optional headings can be definedwith the comment that they may not be required for all documents. The author would then remove those thatwere not needed.Policy Headings may define an effective date, review date, expiration date, policy owner, compliance requirement,filing date, and other fundamental information that is required for all Policies. Headings may be different for anenterprise Policy than those for a department Policy.Process Headings may define Process owner, affected departments, required controls, key outputs, and otherfundamental information that is required for all Processes.Procedure Headings will vary based upon the type of Procedure being developed. Therefore, there may bemultiple Skeletons based on the content.Perform the following to determine the Headings for the Policies, Processes, and Procedures: • Review existing Policies, Processes, and Procedures, and determine the Headings used consistently for a type of document. • Interview audiences to determine types of Headings that are required and those that are optional within a document type.eDocumentation™ Process phasePlanBuildVersion 2.0 eDocumentation™ Build Phase Page 29 of 73
  30. 30. Writing Style Writing StyleWriting Policies, Processes, and Procedures is a collective task; it is not the work of a single person. Therefore,this demands that all participants attempt to use the same writing style. A writing style goes beyond grammar andpunctuation; it is the structure and wording of the Policies, Processes, and Procedures. Writing style is anenterprise standard. Consistent writing style leads to clear, concise, complete, and correct™ documentation.Policies, Processes, and Procedures should be simple and easy to scan and read. Information should bepresented so that it is easy to understand. All documents should be consistent and standard. The reasons for aclear and concise writing style include the following: • User is able to reference and scan a document more effectively. • User is able to focus attention easier on single-subject documents. • Documentation developer is able to develop the documents more effectively. • Documentation developer and authors are able to maintain and change documents more effectively and efficiently. • Documentation developers and authors can be trained in a standard approach. • Documentation can be maintained by multiple authors. • Documentation is standard and legacy documentation can be brought up to the standard. • Modular writing is enhanced.Policies, Processes, and Procedures each have unique writing style attributes. • Policies inform. A Policy clearly describes what the Policy is and why the Policy exists. A Policy is comprehensive and may use narrative and descriptive statements. A Policy does not contain step-by- step instructions. The writing style of a Policy may be more formal and descriptive than that of a Process or Procedure. Depending upon the audience, ‘legalese’ and technical terms are kept to a minimum. • Processes inform and instruct. A Process uses short, simple statements. The writing style condenses content into direct commands. It is used as a high level guide to a Procedure or set of Procedures. When a Process map is used, the text within each graphic is simple and consistent. • Procedures instruct. A Procedure uses step-by-step instructions to describe the steps to perform. They are audience-driven and task-oriented. The objective of the Procedure writing style is to provide material as clearly and concisely as possible. The writing style is simple and direct, yet must be detailed enough to perform the task or step. Lists and tables are readily used to aid user reference.1. Public writing style booksThere are excellent style guides available for purchase. Therefore, this chapter does not attempt to be acomprehensive style guide. When using the eDocumentation™ Writing Style chapter, keep in mind the type ofdocument you are writing and your enterprise; the writing style may need to be specialized.Version 2.0 eDocumentation™ Build Phase Page 30 of 73
  31. 31. Writing Style2. Enterprise writing styleAn enterprise writing style is a combination of accepted rules (for example, grammar) and guidelines created bythe enterprise (for example, consistent terms). It is acceptable to build your own standards based on the followingobjectives: • Maintenance of documentation • Ease of readability for the user • Greater understanding by the userPurchase an established style guide or use an existing enterprise style guide for reference as a starting point.Then, using the information covered in this chapter, determine what applies to your Policies, Processes, andProcedures, and create the style guide that defines your standards. This is an ongoing process. Set up aprocess that allows other Documentation developers to contribute to the enterprise style guide.3. Headings, paragraphs, sentences, lists, and tablesThe building blocks of Policies, Processes, and Procedures are the headings, paragraphs, sentences, lists, andtables. The following are general guidelines: Documents • Limit a document to 3 or 4 pages, if possible. • Use titles, not names of the persons referenced. The names of people holding a title can change over time. • Use functional names, if a title is not available (for example, AP owner). Headings • Use headings to create an outline of a chapter or section. Headings orient audiences to the subject matter and guide the reference process. • Do not use punctuation at the end of a heading, except for a question mark or quotation mark. Paragraphs • Restrict paragraphs to 3 to 5 sentences, if possible. Sentences • Use short, simple, clear sentence structure. Review sentences for excess words. However, avoid taking this guideline to extremes, where the sentence becomes unclear. • Use ordinary and precise words. Avoid wordiness, such as unnecessary modifiers and redundant information. • Avoid jargon and technical slang. Based on the audience, use familiar terms rather than technical words, if possible. • Avoid using software, hardware, or technical terms that can become dated unless required; for example, don’t use ‘HP printer’, use ‘printer’.Version 2.0 eDocumentation™ Build Phase Page 31 of 73
  32. 32. Writing Style • Select specific formats that you will use to emphasize words, phrases, new terms, and examples. (for example, bold, italic, underlined, bold underlined, bold italics, or single quote marks). Use consistently and with care, as maintenance can be difficult. Lists and tables • Use lists or tables within paragraphs, when the paragraph becomes too large. • Format a series of items in a bulleted list or table. • Use a period at the end of each item that is a complete sentence. • Do not use a period for list items that are incomplete sentences. • Capitalize the first word in a list.4. Sentence construction Voice The objective of Voice is to make it easier to determine the ‘actor’ and the ‘action’. If not clear, the audience works too hard to decipher the content. • Active voice is more direct, clear, and shorter; sentences are less complicated. The Documentation developer should always attempt to use the active voice. • Passive voice is less direct. Sentences are longer and are harder for the user to reference. Usage Example Explanation Use active voice. Print the report. Subject performs the action The AP processor prints the expressed in the verb. report. (subject, verb, object) Avoid use of passive voice. The report will be printed by the Object receives the action AP processor. expressed in the verb. (object, verb, subject.) Use Find to locate passive words which are forms of ‘be’, ‘have’, ‘do’. Tense There are three tenses: past, present, and future. Because Policies, Processes, and Procedures address current content, the present tense is normally used. • Use present tense. It is more direct and easier to read. • Avoid using past tense and future tense. Past tense and future tense should be used only when you are referring to something that has occurred in the past or will occur in the future.Version 2.0 eDocumentation™ Build Phase Page 32 of 73
  33. 33. Writing Style Usage Example Explanation Use present tense. Print the report. More direct and easier to read The AP processor prints the and write. report. Avoid use of past tense. The AP processor printed the Past tense uses ‘ed’. report. Avoid use of future tense. The AP processor will print the Future tense uses ‘will’ and report. ‘shall’. Person Person refers to a personal pronoun that represents the speaker (first person), the person spoken to (second person), or the person or thing spoken about (third person). Usage Example Explanation Use second person. Print the report. Represents the person spoken to. Implies ‘you’. Avoid use of first person, if I printed the report. Represents the speaker. possible. Use Find to locate pronouns: ‘I’, ‘we’. Avoid use of third person, if She prints the report. Represents person spoken possible. about. Use Find to locate pronouns: ‘she’, ‘he’, ‘they’, ‘them’. Subject-Verb agreement The verb must agree with its singular or plural subject. Usage Example Explanation Verb must agree with its subject. The AP processor prints the Singular subject report. The AP processor is printing the report. The AP processor and manager Plural subject print the report. The AP processor and manager are printing the report. Singular pronouns that do not Someone prints the report. Too general and ambiguous for refer to a person or position Policies, Processes, and should not be used - ‘someone’, Procedures use. ‘everybody’, ‘nobody’.Version 2.0 eDocumentation™ Build Phase Page 33 of 73
  34. 34. Writing Style5. Parallel structureParallel structure refers to using the same pattern of words, phrases, clauses, and paragraphs. The benefits ofparallel structure include, but are not limited to, the following: • Emphasizes similar types of content, making it more predictable for the user. • Uses consistent syntax and sentence structure for similar types of content, such as headings, lists, screen instructions, report instructions, glossaries, and indexes. • Combines and organizes similar or related ideas and content. • Presents information in a hierarchy or outline within the section or chapter. Guideline examples Parallel structure requires all nouns, all infinitives, all prepositional phrases, all gerunds, or all clauses to be similar. The following are examples of each: Usage Correct Incorrect Nouns The printer was shipped with the The printer was shipped with the cable, power supply, and cable, power supply, and sent software. overnight express. Infinitive phrases The printer has capabilities to The printer has capabilities to fax, to scan, and to print. fax, to print and also scans. Prepositional phrase The printer was shipped from The printer was shipped from Los Angeles by overnight Los Angeles using overnight express. express. Gerunds Resolve printer issues by Resolve printer issues by detecting, analyzing, and detecting the problem, analysis, correcting the problem. and correction. Clauses The printer has capabilities to The printer has capabilities to fax, and also to scan. fax and also scans. Parallel structure examples Parallel structure is used for headings, steps, lists, and text. The following are examples of each: Usage Correct Incorrect Headings and subheadings Printer problems Printer problems Detecting problems Problem detection Analyzing problems Analyze the problem Correcting problems CorrectionsVersion 2.0 eDocumentation™ Build Phase Page 34 of 73
  35. 35. Writing Style Usage Correct Incorrect Steps To print a document, follow To print a document, follow these steps: these steps: Open the document. Open the document. Select Print from the pull From the pull down menu, down menu. select Print. Click OK. Lastly, click OK. Lists The printer has the following The printer has the following printing capabilities: printing capabilities: Color Color printing Two sided Prints on two sides Collate Collates pages Text The printer capabilities are color The printer capabilities are color printing and two-sided printing. printing, two-sided, and collates pages.6. ListsThe proper formatting and punctuation for lists can be difficult for consistency. Use the following as a guideline. Usage Correct Incorrect Capitalize the first word of the The printer has the following The printer has the following each list. features: features: • Color • color • Two-sided printing • two-sided printing • Draft mode • draft mode If the list uses incomplete The printer has the following The printer has the following sentence or sentence fragments, features: features: do not use a period. • Color • Color. • Two-sided printing • Two-sided printing. • Draft mode • Draft mode.Version 2.0 eDocumentation™ Build Phase Page 35 of 73
  36. 36. Writing Style Usage Correct Incorrect Avoid mixing complete The printer has the following The printer has the following sentences and sentence features: features: fragments, if possible. • Color. • Color If you must mix, the following • Two-sided printing. Reports • Two-sided printing which guidelines are suggested: from users indicate this users report is not always • Use a period at the end of feature is not always reliable. each list item. reliable. • Draft mode • Use a sentence fragment • Draft mode. before the complete sentence. The above rules enable the list to adhere to parallel structure Keep the subject matter similar The printer has the following The printer has the following for a list. Do not add extraneous features: features: information to the list. • Color • Color • Two-sided printing. • Two-sided printing, which • Draft mode conserves paper Users are encouraged to use • Draft mode, which draft mode and two-sided conserves ink printing, as it conserves paper and ink. Use bullets, when the list does The printer has the following The printer has the following not have a specific order. features: features: • Color 1. Color • Two-sided printing 2. Two-sided printing • Draft mode 3. Draft mode Use numbers, when the list Perform the following, when Perform the following when requires a specific order. setting up the printer: setting up the printer: 1. Plug electrical plug into • Plug electrical plug into outlet. outlet. 2. Connect cable to pc. • Connect cable to pc. 3. Turn power on. • Turn power on. 4. Load paper. • Load paper. 5. Load printer software. • Load printer software. 6. Print test document. • Print test document.Version 2.0 eDocumentation™ Build Phase Page 36 of 73
  37. 37. Writing Style7. Capitalization and numbers The writing standards for capitalization and numbers are set by the enterprise. The standard should be intuitive and consistent. Capitals Usage Explanation Correct Incorrect Title Capitalize first letter of all How to Print the Report How To Print The Report words in a title except with the New Printer With The New Printer conjunctions, articles, prepositions, and ‘to’ infinitives. Headings Capitalize only the first Report printing Report Printing word. Print reports Print Reports Common industry Do not capitalize unless it system, administrator, System, Administrator, nouns is a proper noun. directory, team, etc. Directory, Team Acronyms Do not capitalize words accounts payable (AP) Accounts Payable (ap) that create the acronym. Capitalize the acronym. There may be exceptions to this guideline. Show acronym within parentheses. Keyboard keys Capitalize first letter of Ctrl key ctrl key each term that identifies Del key DEL key the name of a key. Page Up key page up Key Numbers Usage Correct Incorrect Write out numbers that begin a Twenty-five reports print daily. 25 reports print daily. sentence. Use consistent numbers. Report 3240 prints on the 1st, Report 3240 prints on the first, 15th, and 30th of each month. 15th, and 30th of each month. Use a combination of numbers Five reports are printed on the 5 reports are printed on the 1st, and written numbers for clarity. 1st, 15th, and 30th of each 15th, and 30th of each month. month.8. Punctuation Commas The rules for the use of commas are too extensive for eDocumentation™ Style Guide to cover. Refer to a standard grammar reference book. However, the following are examples of uses of commas that are oftenVersion 2.0 eDocumentation™ Build Phase Page 37 of 73
  38. 38. Writing Style encountered when writing Policies, Processes, and Procedures. They are presented here only to save you time, if you are uncertain about the correct usage. Usage Correct Incorrect The same subject for both clauses is expressed only once and is connected with ‘but’ or ‘and’. ‘but’ - Separate with comma. The printer is working, but is The printer is working but is very very noisy. noisy. ‘and’ - Do not separate with The printer is working and is The printer is working, and is comma. very quiet. very quiet. The second part of a two-part The users did not fix the printer, The users did not fix the printer sentence, introduced by ‘yet’, as the office closed. as the office closed. ‘for’, ‘or’, ‘nor’, ‘while’ or ‘as’ (because) is separated with a comma. If an introductory phrase starts Because the printer was noisy, it Because the printer was noisy it the sentence, set off with had to be fixed. had to be fixed. comma. Use of ‘that’ tells which one. The printer that is noisy has The printer, that is noisy, has Do not set off with a comma. been fixed. been fixed. Tells which one is noisy. Use of ‘which’, ‘where’, ‘when’ The printer, which is noisy, has The printer which is noisy has only adds a fact. been fixed. been fixed. Set off with a comma. Only adds a fact. Colons Usage Correct Incorrect Use a colon when introducing a The printer output can be The printer output can be list that contains ‘the following’, produced in the following ways: produced in the following ways. ‘as follows’, etc. Use a period if the introduction is The printer output can be The printer output can be a complete sentence. produced in different ways. produced in different ways:Version 2.0 eDocumentation™ Build Phase Page 38 of 73
  39. 39. Writing Style Semicolons Usage Correct Incorrect If two clauses are not joined by The printer’s output is excellent; The printer’s output is excellent: a conjunction and the second the colors are vivid. the colors are vivid. clause provides further information, use a semicolon. If two clauses form a compound The printer’s output is excellent. sentence, they can be written as The colors are vivid. two sentences. Hyphens Usage Correct Incorrect Use a hyphen to combine two or Run-of-the-mill Run of the mill more words into a single word. Do not use a hyphen for email, online, database e-mail, on-line, data-base common industry-accepted terms. Use a hyphen when the re-enable, co-organizer reenable, coorganizer combination results in double letters. Not all words follow this rule. If unsure, consult the dictionary. Quotation marks Use single quote marks ( ‘ ‘ ) instead of double quote marks ( “ “ ). This guideline is for ease of maintenance.9. AbbreviationsAbbreviations are defined in the glossary that is created during the eDocumentation™ Consistency of Terms task.Determine the common abbreviations that will be used by your organization and set the usage standard. Theabbreviations should be unique, clear, and definitive. A glossary should define all abbreviations. Abbreviationsmay be developed for the following - however, the list is not all-inclusive: • Departments • Locations • Titles • Systems • FunctionsVersion 2.0 eDocumentation™ Build Phase Page 39 of 73

×