Technical Report Writing and Documentation - ?· Technical documentation is one of the most important…

  • Published on

  • View

  • Download

Embed Size (px)


  • Spring 2005 1

    Technical 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 investigat-ing 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 cant 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 techni-cal 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 writ-ing, are covered in this article and should help you develop into a good technical writer.

    Technical DocumentationGood reports comprise four to

    five (or more) essential sections or components. Hopefully, over time, standardized report formats will be developed, each being in-formative, 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 com-ponents 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.

    Technical Report Writing and Documentation


    by Rod OlingerElectrical Reliability Services

  • 2 NETA WORLD Spring 2005 3

    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 find-ings 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 col-lected test data for each component or piece of equip-ment. 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 main-tained. 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 hand-written 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).

    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 emphasiz-ing 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 GrammarGrammar, 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 en-hance 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 BetterSo you just completed a very large shutdown main-

    tenance project for your customer, and now its 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?

  • 2 NETA WORLD Spring 2005 3

    Forms and Data ManagementForms 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 read-ability. 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 elec-tronic 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. Trans-mission to the collection point should be as required by the lead technician.

    Remember, while reports can be written and re-written, 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 WritingTo summarize, I have stressed the importance of

    writing high quality technical documentation and sug-gested 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 previ-ously 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 assis-tance.

    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.

    If you catch yourself thinking about these questions, its 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 tech-nician knows the job expectations, scope, and pre-scribed 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 dif-ferences in order to meet customer expectations.

    Be sure the customer is informed of significant issues: Ensure the customer is made aware of sig-nificant 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 de-ficiencies 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, us-able 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.


    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. Dont 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. Dont forget to outline the job scope and test procedures used and address discrepancies or concerns so corrective actions can be taken.

    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 pass-fail 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 rep-resent, 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.


View more >