Feature
Report Writing
Technical
and Documentation
T
echnical documentation is one of the most important aspects of any
electrical power system acceptance and maintenance project for
NETA technicians but often gets the least attention. To emphasize
the importance of good reports with accurate support documentation,
simply look at it this way: reports are the documented history of any
acceptance or maintenance project. They describe the condition of the
equipment tested or maintained. This is what our customers need. As
NETA technicians, we understand that quality documentation is also a
critical tool when troubleshooting and can be invaluable when investigating equipment failures and establishing trends over time.
Take this a step further and think about the customer. The customer
may use your report documents in a multitude of ways, including:
Planning for equipment replacement or upgrades
• Pursuing equipment repairs and corrective actions
• Planning for facility changes (e.g., expansion or changes
to facility use)
• Using reports to support warranty or defect actions.
•
Like me, if you have ever been on the receiving end of a discussion
with a customer who says “I can’t make heads nor tails of this report”
or “What does your finding such and such mean to me?” you quickly
understand the importance of good reports.
Several key elements are part of every report and individual technical documents. These topics, including technical documentation (with
and without electronic data collection), technical grammar, managing
projects better, forms/data sheet management, and keys to good writing, are covered in this article and should help you develop into a good
technical writer.
Spring 2005
by Rod Olinger
Electrical Reliability Services
Technical Documentation
Good reports comprise four to
five (or more) essential sections
or components. Hopefully, over
time, standardized report formats
will be developed, each being informative, easy to use, and easily
readable. The sections typically
are:
1. Scope of the Project: Tells the
customer what was tested and/or
maintained so it is clearly known.
This can be a summary of components by location (e.g., main
switchboard, substation #1, etc.)
or by equipment type (medium
voltage switches, protective relays,
molded case circuit breakers, etc.),
or both, whichever best suits the
customer. Bulletized lists or tables
are effective for this.
1
2. Procedures Used: States what methods were used.
This can be as simple as “testing performed to NETA
ATS-2003,” or the procedures may be written out
— whichever is best used by your customer. In many
cases the customer may have a preference, and it is
beneficial to ask. Bear in mind that the procedures
stated as the ones used should be accurate and reflect
the actual work performed. Blanket statements such
as “all testing was done to NETA ATS-2003” are quick
and easy but may not accurately define the level of
work performed.
3. Results from the Testing: Contains all test results.
This very important section of a report may take the
most effort. The goal is to advise the customer of findings that warrant further action, delineate what the
impacts may be on the electrical system or facility, and
suggest follow-up or corrective action. Be specific, and
write so the customer understands what the problem
is and what the options are for remediation. A good
example of the sort of detail needed is as follows:
“Circuit breaker MSB-3 fails to trip on a ground
fault condition. If not corrected, (a) nuisance trips
could occur at upstream protective devices affecting a
larger section of the electrical system, and (b) optimum
protection to the connected circuit components has
been compromised. The breaker should be repaired or
replaced and retested to verify proper operation.”
It is essential that significant findings are stressed
to the customer immediately on the job site and in the
written report.
4. Support Documentation: Includes copies of collected test data for each component or piece of equipment. This documentation is absolutely critical. Reports
are written based on the actual test data collected, and
the test data is a permanent record of the as-found
and as-left condition of each item tested and/or maintained. The data on these forms should be the actual
results gathered during testing and comply with the
procedures section of the report. The format for this
collected data can vary widely from handwritten data
on preprinted forms to electronically generated forms
using a wide array of software.
Much has been discussed about this issue of handwritten versus electronic data collection. It is not my
intent to persuade the use of one format over the other.
Both handwritten and electronic methods have their
pros and cons (although in this digital age, electronic
development and transmission of data should not be
overlooked).
•
2
Handwritten forms: Pro: They are “real-time” and
accurate since they are generated as each item is
tested. Con: The data can be illegible if not written
neatly; forms can be damaged, wrinkled, or even
lost. They are not easily archived, transmitted, or
reproduced.
•
Electronic forms: Pro: Easy to read, legible, and can
be easily reproduced, stored, and archived. Con:
Computers can crash, and the data can be lost (be
sure to back up your data). “Cut and paste forms”
for numerous similar components may introduce or
carry over data mistakes (e.g., test results, etc., must
be unique for each component, so use caution not to
carry over data from one component to another).
5. Additional Information: Covers a variety of topics
in additional sections of a report. A few examples may
include a summary of the overall project emphasizing significant points or events, special requirements
mandated by the customer, safety related matters
(e.g., lock-out/tag-out used, unique site constraints,
back feed sources), and photos to enhance or clarify
reports.
Technical Grammar
Grammar, as it applies to technical reports, is
somewhat different compared to a purely narrative
document, but, grammar is still important. Avoid
spelling mistakes, misused or misapplied commas
and colons, and most importantly, use good word
choices. Remember, the goal is for a customer (many
of whom are not strong technically) to understand
your documents and apply or act on what you wrote.
Terms like harmonics, power factor, and capacitance need
to be in your report, but when you bring attention to
these topics it is helpful to expand with some “lay
person” narratives for customer readability. I can recall
numerous conversations with customers who receive a
superbly written and technically accurate report only
to hear “What does this mean?” or “Can I still use the
system … or will it fail?”
Technical documents are intended predominantly
to report facts and document findings. For this style of
writing, the use of tables, spreadsheets, and bulletized
statements can be appropriate and effective. Narrative
writing in reports is primarily used to clarify and enhance the factual information and should be done in
a concise to-the-point fashion. Save descriptive terms
(extremely, highly, dangerous, etc.) to call attention to
significant issues and support these terms with factual
data and findings.
Managing Projects Better
So you just completed a very large shutdown maintenance project for your customer, and now it’s time
to draft the report. You have 10 to 12 stacks of data in
various formats using a multitude of forms: 50 percent
are handwritten, and 50 percent are electronic. Where
do you start? Did you test everything you contracted
to test? Were significant issues identified while on
the job site and the customer made aware of them?
NETA WORLD
If you catch yourself thinking about these questions,
it’s probably time to devise a method to plan future
projects and make better reports. The following have
helped produce better reports.
•
Think through the job before you commence
testing: Assign personnel and equipment to get
the job done efficiently while making good use
of test technicians’ skills. Lay out the job to cover
every item to be tested so that nothing is missed.
Account for back feeds, lock-out/tag-out, and
other unique needs (e.g., temporary power). If
this is a repeat customer, review previous reports
for trends and findings and focus on the current
status of these issues. This is a good time to plan
your report layout and consider formatting of the
project scope.
•
Plan your data collection and outline the standards
to be used: As much as possible have all technicians
use standard forms and formats. Be sure each technician knows the job expectations, scope, and prescribed procedures (provide test procedures to be
used). Is it a 100-percent-NETA-standards job or are
the requirements abbreviated or modified? Many
customers have unique procedures that vary from
NETA, and it is important to understand any differences in order to meet customer expectations.
•
Be sure the customer is informed of significant
issues: Ensure the customer is made aware of significant findings as they occur. Safety concerns or
equipment failures may affect the ability to restore
power or ensure the equipment functions properly.
Track significant issues to be sure they are included
in your report.
•
Organize the data and structure a report: If the first
three items above are done well, this job should be
straightforward. Scour data collection documents in
detail when drafting the report. The majority of deficiencies will be documented on test data forms. If
time permits, have an objective reader review your
report for readability and comprehension. This is
the litmus test that you have written a concise, usable document.
Few things can be more challenging than talking
with an angry customer about a report or portions of
a report and not being able to explain adequately or
support all the findings or defend why all elements of
the contracted scope were not performed.
Spring 2005
Forms and Data Management
Forms and data are the backbone of any report, and,
thus, their management is of supreme importance.
Remember, reports are going to be generated from
the data collected, and most likely the reports will
be written by someone who does not have intimate
knowledge of the equipment tested. As a manager,
I frequently reviewed reports and can recall being
impressed with how well some reports were written
and supported with quality data, or, conversely, recall
those occasions where a report appeared confusing
or inconclusive, with inaccurate or incomplete data.
The trick is to get it right the first time, since it can be
all but impossible to reconstruct data collection after
the fact.
Every technician on a project should be using the
same forms to ensure that standard formats are used.
This makes for a nice presentation and ease of readability. If handwritten forms are used, it is imperative
that the legible forms get to a common collection point
(or person) as soon as possible to minimize loss or
damage to the forms. This should be emphasized at
the project onset. One option is to require all data be
turned in before departure from the job site. If electronic forms are used, data should be backed up onto
a secondary device (server, CD, floppy disk) to avoid
loss of data stored on an individual hard drive. Transmission to the collection point should be as required
by the lead technician.
Remember, while reports can be written and rewritten, data collection does not offer the benefit of a
second chance. Once an electrical system is put into
service, retesting and performing additional testing
is not easily done.
Keys to Good Writing
To summarize, I have stressed the importance of
writing high quality technical documentation and suggested some of the tools to achieve this goal. Below
are listed some keys to apply and make part of your
report and technical writing process. Some have previously been discussed and most are common sense, but
the bottom line is that, with time and practice, good
technical writing practices will become habit.
•
Know your subject: You must understand the data
and be able to interpret it to write an informative
report. Seek guidance if you need technical assistance.
•
Write for ease of comprehension: Remember, we
are writing for the reader, who needs to understand
the report in order to get value from it and use it
effectively. Use correct technical terminology but
offer clarifications appropriately geared for the lay
person.
3
•
Develop your skills: Have others read and critique
your reports. Can they understand the report? Push
yourself to improve.
•
Write to express, not to impress: This is technical
writing not a novel, so keep the contents concise and
to-the-point. Don’t bury important facts between
flowery words.
•
Organize the report: Put things in order that make
sense to the customer or end user. Data should be
sorted by equipment/component type, voltage
class, and/or location. Don’t forget to outline the
job scope and test procedures used and address
discrepancies or concerns so corrective actions can
be taken.
•
4
Be legible and accurate: Unreadable reports are
of no value. Electronically developed documents
are the best, but only if errors and mistakes are
not carried over. Be sure that the documentation is
factual and meaningful. NETA has numerous passfail criteria in the Maintenance Testing Specifications
and Acceptance Testing Specifications to assist with
interpretation of collected test data.
A report is generally the only tangible result left
with a customer. The quality of this document is
reflective not only of the NETA company you represent, but more importantly, the document should
accurately reflect and document the electrical power
system tested and maintained. There is an old adage
“No job is complete until the paperwork is done!”
As NETA companies, our goal is to be tools to help
customers provide safe, reliable power. Our reports
and technical documents are the record to document
this service.
Rod Olinger is the Manger of Training Services for Electrical
Reliability Services and is focused on providing custom training
to clients. Rod has been working in field service and training in
the power industry for over twenty years. He is a NETA Certified
Sr. Technician, Level IV.
NETA WORLD