2. Table of Contents – Build
Table of Contents – Build
Table 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. 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. 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. eDocumentation™ Process Flow
eDocumentation™ Process Flow
The eDocumentation™ Process is a set of guidelines, not decrees, that guide the Documentation developer
through the research, development, and implementation of Policies, Processes, and Procedures. The objective is
to 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 the
diligence 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 phases
There are four major phases that comprise the eDocumentation™ Process. The phases encompass the tasks
that need to be reviewed and performed as the project progresses, depending upon the company, project, and
scope.
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. 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
8. Content Research
Content Research
Policy, 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 implementation
phases. Content research is the task of conducting a thorough and comprehensive study of the subject matter
that will become the content for the Policies, Processes, and Procedures. The amount of research required is
based 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 by
analysts, designers, managers, or executives. However, the research previously performed will not include all the
information that will be required by the Documentation developer. The Documentation developer’s task is to
compile 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 ‘connecting
the dots’, information that will be required by the users may be missing or tasks not fully defined. Therefore, the
Documentation developer is looking for the gaps in the previous research. There will certainly be gaps, as the
research 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
audience
Version 2.0 eDocumentation™ Build Phase Page 8 of 73
9. Content Research
1. Research approach
The 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™ Planning
phase. 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 research
approach:
• 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 audience
The 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 for
management, but may be effective for users.
3. Research methods and tools
During 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 for
your enterprise or department. Evaluate the available methods and tools and determine the most effective way to
attain the needed information from users and Project team members. Using the Audience Evaluation, consider
the following questions for each audience, when selecting research methods and tools:
Version 2.0 eDocumentation™ Build Phase Page 9 of 73
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 sites
Version 2.0 eDocumentation™ Build Phase Page 10 of 73
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. Content Research
4. Prepare for research
To 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. During
the 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. 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 plan
Use the information from the eDocumentation™ Planning phase.
• Project scope
• Audience evaluation
• Working team
• Review team
• Project team
• Content audit and evaluation
From the preliminary research steps, use the information obtained from the following research tasks:
• Existing documentation
• Research methods
• Training sessions
• Design and requirements meetings
Based 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. 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 sufficient
The Research plan is published to establish who and what is involved during the research phase. Comments and
changes should be welcomed. It is important to obtain as much information as possible at the beginning of the
project.
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 can
Version 2.0 eDocumentation™ Build Phase Page 14 of 73
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. 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 test
Process and Procedure research requires ‘hands on’ methods - especially testing and verification. Because the
documentation is the ‘how to’, the Documentation developer must be certain the Process and the Procedure are
correct - 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; new
information always surfaces.
Testing may be the first opportunity the Documentation developers, who become involved in the project ‘later in
the game’, have to observe and analyze the system and Processes in detail. In that case, being involved with
testing 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 Process
It must be emphasized that during testing there may be excellent scenarios prepared by the subject matter
experts. The scenarios can ‘almost’ be converted directly into Processes and Procedures. Of course, this will
vary with project and subject matter experts, as their expertise will vary.
eDocumentation™ Process phase
Build
Version 2.0 eDocumentation™ Build Phase Page 16 of 73
17. Collaboration
Collaboration
Collaboration is the sharing of information. Because Policies, Processes, and Procedures require the knowledge
of many people, it is imperative that there be a high level of collaboration. The subject of collaboration can be
very broad and, at times, general. The collaboration process can be structured or unstructured. We are only
addressing methods that can be effective in sharing and managing information during the development and
maintenance of Policies, Processes, and Procedures.
Types of collaboration
In order for Policies, Processes, and Procedures to retain the status of clear, concise, complete, and correct™, a
method for users to collaborate with the Documentation developers is required. Examples of needed
collaboration 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 content
Content 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 matter
experts, technical resources, and management give their input – changes, deletions, suggestions. This is a very
dynamic 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. Collaboration
Development
Usually Policy, Process, and Procedure collaboration occurs at the development level. Project teams are formed
and 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 documentation
If you attempt to implement and use collaboration software, be aware that you will need to create and foster a
knowledge culture in order for team members to be willing to use the tool. In essence, this is creating a new
project that will require implementation, training, and support. Some enterprises may have the collaboration
software, but the software may not be widely available to all projects. However, you can still use collaboration
principles 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 the
documentation. For example, your company may have a portal where published documents are accessible.
However, the previous steps are not managed by the portal.
Changes
The reporting and feedback from users is usually less after implementation. Unless there is a documentation
feedback system, there is will be no way – other than email – to report problems. The Policies, Processes, and
Procedures 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 issues
are consolidated, and documentation issues can be immediately changed – if required – or incorporated in the
next scheduled review.
Usability
Feedback of usability factors should be promoted. Testing usability factors does not replace workplace use and
reference of Policies, Processes, and Procedures. Setting up a web-based issue reporting process would
accommodate usability feedback.
Methods
There are a number of methods available for collaboration. Determine if your company has collaboration software
or processes that would be available to your project. If none are available, you will need to develop and
implement 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. 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 board
Setting up a knowledge and collaboration culture is not a small task. Getting everyone on board can add time to
a project.
eDocumentation™ Process phase
Build
Version 2.0 eDocumentation™ Build Phase Page 19 of 73
20. Interviews
Interviews
Interviews are an important part of the Research eDocumentation™ phase. When researching content for the
development of Policies, Processes, and Procedures, it is necessary to interview people who have a thorough
knowledge of the subject matter. Based upon the interviews, the Policies, Processes, and Procedures are
developed.
Starting the interview process can be overwhelming. Depending upon the scope of the project, the process
requires coordination and planning between those conducting the interviews. Interviewees can become quite
upset if they are asked the same questions by multiple people. Therefore, this phase requires planning in order
for the interviews to be effective and efficient.
1. New development
On new development and larger projects, training may be conducted for the project and the user team. In
addition, there are design meetings and reviews that can give Documentation developers required background
and knowledge. At times the project leaders may be hesitant to allow Documentation developers to attend key
planning meetings. This is a mistake. The Documentation developers communicate the required information
and, therefore, must completely understand the information. It is time well spent to include Documentation
developers. The knowledge gained from the users, the subject matter experts, and the project team is vital to
preparing Policies, Processes, and Procedures. Including all involved people in the beginning of the planning
phase puts everyone on the same page and, in the end, is profitable.
2. Nonlinear task
The interview tasks are not linear. Most project plans have a set timeframe to gather requirements and develop
the resulting Policies, Processes, and Procedures. However, during the development process, many questions
arise that require clarification. The Documentation developer must build time into the schedule for reviews and
follow-up.
3. Types of interviews
There are different methods for conducting interviews. Determine the type of interview to conduct, based on the
phase of the project, type of information required, the group to be interviewed, and the required outcome. The
following 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. 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 interview
You should cast a wide net in determining who to interview. The most successful projects encourage the
Documentation developers to interview whomever they think they need. This approach can be abused, if authors
have not planned and are not fully prepared for their interviews. A user should not be asked the same questions
by multiple Documentation developers.
If the Documentation developers are in a centralized department or on a large project, there is usually a hierarchy
of who is allowed to talk to users and others. This is understandable. However, the Policies, Processes, and
Procedures integrity requires that Documentation developers not be reduced to clerks. The more layers of people
that 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 representatives
Version 2.0 eDocumentation™ Build Phase Page 21 of 73
22. Interviews
• IT / Technical
• Management
• Training department
• Vendors
5. Guidelines for interviews
Preparations 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. 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. 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 approach
The following is a brief approach to conducting interviews. Answering these questions will provide basic interview
preparation.
• 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 phase
Build
Version 2.0 eDocumentation™ Build Phase Page 24 of 73
25. Templates and Skeletons
Templates and Skeletons
A Template is a style guide for documents. Templates enable all Policies, Processes, and Procedures to be
consistent in format and appearance. This consistency is an enormous benefit for the users. They do not have to
use 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. The
Documentation developer is able to concentrate on creating the content for the document and not on formatting
the document.
A Template has built-in functionality, which can include predetermined styles, formatting, boilerplate text, auto text
entries, macros, custom toolbars, and shortcut keystrokes embedded in the Template.
Template controls
The ability to change a Template by the individual authors varies, depending upon the authoring software. Some
software has stringent controls, whereby the author cannot change the Template. Other software allows all
authors 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 a
final step. Although this may be viewed as ‘extra work’, in the long view it will save time.
Template design
A 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 required
for 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. 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 Skeleton
Related documents or a document set (Policies, Processes, Procedures, Quick Reference Guides, Screen
Instructions, 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 different
content purposes and format layouts.
The eDocumentation™ Process uses the term ‘Skeleton’ to describe a document that is used for a specific
document type (Policy, Process, or Procedure), but is based on a single Template. It contains the preset content
for that specific type of document (for example, a Policy document or a Procedure document), but the formatting
is based on a single and shared Template. Therefore, a document set - Policies, Processes, and Procedures - is
based on a single and shared Template.
Skeleton documents are meant to be ‘Fill in the blanks’ rather than ‘Start from scratch’. The subject matter
experts can complete the content without having to deal with the complexities of Templates. As a note, a major
advantage in using Skeletons is that the content of the Policies, Processes, and Procedures is not interchanged
and combined into a single document. This enables using modular writing.
Version 2.0 eDocumentation™ Build Phase Page 26 of 73
27. Templates and Skeletons
The 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 specific
document 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 x
Version 2.0 eDocumentation™ Build Phase Page 27 of 73
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. Templates and Skeletons
Standard Skeleton Headings
The Headings content differentiates a Policy, Process, or Procedure. Setting up predefined Headings in a
Skeleton guides the authors and Documentation developers, when developing the documents. For example, a
Policy will not have system instructions or report instructions. As a guideline, optional headings can be defined
with the comment that they may not be required for all documents. The author would then remove those that
were 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 an
enterprise Policy than those for a department Policy.
Process Headings may define Process owner, affected departments, required controls, key outputs, and other
fundamental information that is required for all Processes.
Procedure Headings will vary based upon the type of Procedure being developed. Therefore, there may be
multiple 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 phase
Plan
Build
Version 2.0 eDocumentation™ Build Phase Page 29 of 73
30. Writing Style
Writing Style
Writing 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 and
punctuation; it is the structure and wording of the Policies, Processes, and Procedures. Writing style is an
enterprise 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 be
presented so that it is easy to understand. All documents should be consistent and standard. The reasons for a
clear 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 books
There are excellent style guides available for purchase. Therefore, this chapter does not attempt to be a
comprehensive style guide. When using the eDocumentation™ Writing Style chapter, keep in mind the type of
document 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. Writing Style
2. Enterprise writing style
An enterprise writing style is a combination of accepted rules (for example, grammar) and guidelines created by
the enterprise (for example, consistent terms). It is acceptable to build your own standards based on the following
objectives:
• Maintenance of documentation
• Ease of readability for the user
• Greater understanding by the user
Purchase 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, and
Procedures, and create the style guide that defines your standards. This is an ongoing process. Set up a
process that allows other Documentation developers to contribute to the enterprise style guide.
3. Headings, paragraphs, sentences, lists, and tables
The building blocks of Policies, Processes, and Procedures are the headings, paragraphs, sentences, lists, and
tables. 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. 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. 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. Writing Style
5. Parallel structure
Parallel structure refers to using the same pattern of words, phrases, clauses, and paragraphs. The benefits of
parallel 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 Corrections
Version 2.0 eDocumentation™ Build Phase Page 34 of 73
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. Lists
The 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. 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. Writing Style
7. 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 often
Version 2.0 eDocumentation™ Build Phase Page 37 of 73
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. 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. Abbreviations
Abbreviations 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. The
abbreviations should be unique, clear, and definitive. A glossary should define all abbreviations. Abbreviations
may be developed for the following - however, the list is not all-inclusive:
• Departments
• Locations
• Titles
• Systems
• Functions
Version 2.0 eDocumentation™ Build Phase Page 39 of 73
40. Writing Style
10. Examples
The formatting of Examples should be consistent for all documentation. The following are suggestions; however,
there are no ‘hard and fast’ rules.
Usage Example Explanation
At beginning of sentence For example, the printer - - - - - Use comma after ‘example’.
In middle of sentence - - - - -(for example, cable and Use comma after ‘example’ and
power supply) - - - - - - enclose the example in
parentheses.
As a paragraph Example: Use colon after ‘Example’ and
To print the document - - - - - give the example on next line.
Do not use e.g. or i.e. These should not be used. The abbreviations can be
confusing or misinterpreted.
11. Slash marks
Usage Correct Incorrect
It is acceptable to use a slash Press the on/off switch to turn off
mark to imply a combination the printer.
such as ‘read/write’, ‘on/off’. Press the on/off switch to turn on
the printer.
Do not use a slash mark to imply Select either the print button or Select the print/cancel button.
a choice, such as ‘he/she’, the cancel button.
‘either/or’, ‘print/cancel’, etc.
Use of and/or is acceptable, if Print the report using white Print the report using either
the items listed are acceptable and/or blue paper. white and/or blue paper.
both together (‘and’) or Implies the following: Implies the following:
individually (‘or’).
white and ‘blue paper either white and blue paper
white ‘or’ blue paper either white or blue paper
12. Text and usage
To emphasize and/or give a specific meaning to words or phrases, format the word or the phrase using any
combination of the following:
• Bold
• Italics
• Underline
• Single Quote
• Color
• Font
Version 2.0 eDocumentation™ Build Phase Page 40 of 73
