Ideal opportunity awaits technical communicators
by David Dick, Washington, D.C. Chapter
Editor’s note: David, an Associate Fellow and member of the Washington D.C. Chapter of STC, discusses the critical nature of engineering/project documentation, and how the technical writer can fill a vital role.
Introduction
Short deadlines force project teams to quickly design, test, and release the product with little or no design documentation. If these documents are written, they generally are not well-written and are not comprehensive. The fact of the matter is that most project teams do not have enough staff to design the product, let alone write and manage documentation. This situation creates an ideal opportunity for technical writers to assist the project team in more ways than writing a user guide.
Why well-written documents are not optional
Did you know that the greatest inventors of our time kept intricate notes of their inventions? One such inventor was Thomas Edison. Although he is credited with perfecting the light bulb, he also conducted experiments to perfect car batteries, film, and the phonograph to name a few. His lab in West Orange, New Jersey includes a library of books that detail his inventions including product designs, test plans, and test reports.
These days, most product development teams avoid documenting their designs because they think the proof of their work is the product — not the document. When management demands documentation, project teams claim that they are engineers, programmers and developers — not writers. Agreed, so why not hire technical writers to document the product design and leave the product development to the experts? Technical writers know how to ask constructive questions of subject matter experts, and they know how to adapt the writing style to the target audience.
Essential artifacts
Whether your organization follows ISO 9000 or CMMI, each phase of development requires artifacts (documents) for each phase of the development cycle (that is, specification, architecture, design, implementation, and testing). No matter how large or how small the project, it cannot be without the following artifacts, all of which can be written with the help of technical writers:
- Project management plan
- System requirements specification
- Functional requirements specification
- Requirements traceability matrix
- Design document
- Test plan
- Test report
- Meeting minutes
Project management plan
Every project needs to answer the proverbial questions: Who, What, When, How and Why. A project that cannot address these questions is probably a project that is doomed to fail, and failure is not an option. The solution is to create a Project Management Plan.
The Project Management Plan defines the project scope, tasks, schedule, allocated resources, and interrelationships with other projects. It incorporates the risk management plan, which identifies, assesses, and ranks potential risks to the system development project; develops plans to mitigate these risks; and provides a control mechanism to monitor, report, and direct all risk mitigation activities. And it provides a framework for the project manager to conduct meetings to discuss progress, issues, and constraints.
A project without a Project Management Plan is like taking an ocean voyage without maps and a compass; the project team has no direction and guidelines. Even if the information is written in a notebook, and the milestones drawn on a board, it’s better than nothing at all. The Project Management Plan should be distributed to the project team and project stakeholders at the onset and updated as needed throughout the project.
Suggested Resource: The Project Management Institute (www.pmi.org) provides templates and instructions on all facets of project management.
System requirements specification
Whether a project involves building a house, a bridge, or designing the next generation computer, it must satisfy somebody’s wants and needs. A system requirements specification (SRS) (also referred to as the software requirements specification) is a document that identifies the users’ (client’s) expectations of the product. The SRS must be well-written and precise, without ambiguity, because the outcome of the product depends on it. A well-formed requirements document identifies a product’s functionality (a capability) that can be validated, solves a customer problem or achieves a customer objective, and qualified by measurable conditions and bounded by constraints. The IEEE Standard 830-1993, Recommended Practice for Software Requirements Specifications, is an ideal source for understanding good structure and layout, and provides templates for structuring the content.
Business analysts follow a process that involves meeting with system owners, users, and project stakeholders to identify the product’s context of use. The SRS forms a contractual agreement for design and performance of the product. The SRS provides a basis to estimate costs and scheduling, a baseline for verification and validation of requirements, and a basis for future enhancements of the finished product. That’s why it’s important for the system owners, users, and project stakeholders to work together to create the SRS; because once it is approved, any and all changes must adhere to a process to control changes.
A project that has no SRS has no agreement for the design of the product, and no reference for the project team to follow. E-mails, meetings and telephone calls are no substitute for an SRS. Mistakes made collecting system requirements are the costliest. Failure to manage changes to requirements causes the project to spiral out of control and over budget.
Suggested resources:
“Recommended Practice for Software Requirements Specifications,” IEEE standard 830-1993
“Writing Software Requirements Specifications” by Donn Le Vie, Jr. on the TECHWR-L website.
http://www.techwr-l.com/techwhirl/magazine/writing/softwarerequirementspecs.html
“Issues in Requirements Elicitation” by M. Christel and K. Kang on the SEI/Carnegie Mellon Software Engineering Institute website. (Sept 1992)
http://www.sei.cmu.edu/publications/documents/92.reports/92.tr.012.html
Functional requirements specification
Functional Requirements Specification
When the SRS is approved; the next step is to define the internal workings of the product. The Functional Requirements Specification (FRS) describes the calculations, technical details, data handling, processing and other specific functionality. All of which are supported by non-functional requirements that impose constraints on the design or implementation (such as performance requirements, security, quality standards, or design constraints).
The FRS describes the required behavior, which may come from organizational or business rules, or discovered through elicitation sessions with users, stakeholders, and other experts within the organization.
A project without an FRS has no agreement for design of the required behavior of the product, and no resource for the project team to design the product. E-mails, meetings and telephone calls are no substitute for well-written FRS. The FRS must be updated when changes are approved to the SRS. And just as with the SRS, mistakes made in the functional requirements are the costliest.
Suggested resource: “Task Descriptions as Functional Requirements,” by S. Lauesen. IEEE Software. (Mar/Apr 2003)
http://ieeexplore.ieee.org/iel5/52/26575/01184169.pdf?arnumber=1184169
Requirements traceability matrix
Requirement traceability matrix
According to Leffingwell and Widrig in Management Software Requirements, every project must have the ability to trace requirements artifacts through the stages of specification, architecture, design, implementation, and testing to assure quality software implementation. The ability to track these relationships and to analyze the impacts of changes form a key thread throughout many high-assurance software processes, particularly in life-critical medical products and business-or mission-critical activities.
Many project teams oppose creating the RTM because it takes time to write and effort to maintain, and brings no added value to the product — so they think. Allow me, if you will, to describe why the RTM is essential to every project.
The Requirement Traceability Matrix serves two purposes:
- Lists the requirements. Only by validating the product against the requirements can the project team verify that the product is delivered according to specification.
- Traces the origin of the requirements, and identify how they are satisfied; how they are tested; and what impact will result if they are changed.
Traceability matrices can be created using a variety of tools including requirements management software, databases, spreadsheets, or even with tables or hyperlinks in a word processor. It makes no difference what tool you choose to create the RTM, so long as it is well-written and maintained.
Without a RTM the project team cannot verify that the requirements are met, and cannot identify affected system components when there is a requirements change, affected components allows the impact of requirements changes on the system to be determined, facilitating cost, benefit, and schedule determinations.
Suggested resource: Requirements Engineering (Second Edition) by Elizabeth Hull, Ken Jackson, and Jeremy Dick (2005). Springer. pp. 9-13, 131-151.
Design document
When the FRS is approved; the next step is to create one or more design concepts. The Design Document communicates decisions (concepts) on how to create the product. Diagrams show how functions and features work, the connectivity of components and, if the design is for a software product, diagrams the user interface. Depending on the circumstances, approval of the design concept may be a pre-requisite before development begins. A well-written design document addresses the requirements stipulated in the system requirements specification and functional requirements specification, and how the design satisfies them. Scott Hackett writes in How to Write an Effective Design Document that the hardest part of writing a design document has nothing to do with the writing. The difficult part is working through the logical design before coding.
Suggested resources:
“Writing a Design Document” by Harvard Computer Science course staff. (Feb 2007)
http://www.fas.harvard.edu/~lib51/files/design_doc.pdf
“How to Write an Effective Design Document” by Scott Hackett on the SlickEdit Developer Blog. (May 2007)
http://blog.slickedit.com/?p=43
Test plan
Every product should be thoroughly tested to verify and validate that it satisfies the requirements for which it is intended.
A test plan identifies the objectives, scope, approach, and focus of product testing. The process to prepare a test plan is a useful way for the project team to consider the efforts needed to verify and validate the acceptability of the product, and if it satisfies the requirements stipulated in the SRS and FRS. The test plan should be detailed enough to be useful, but not so thorough that no one outside the test group will read it.
Test plans should be written to cover the following types of testing:
- Integration testing is conducted to validate if the individual software modules (combined and tested as a group) function properly.
- Unit testing> validates that a particular module of source code works properly.
- User acceptance testing> (UAT) is conducted to validate if modifications or additions satisfy requirements. In software development, UAT is one of the final stages of a project and will often occur before a client or customer accepts a new system.
- Usability testing> measures how well people can use some human-made object (such as a web page, a computer interface, a document, or a device) for its intended purpose, i.e. usability testing measures the usability of the object.
Without a test plan, people testing the product do not have guidelines for which features and functions to test and expected results. Allowing testers to “play with the product” or “try to break the product” is not a substitute for structured testing.
Suggested resources:
“How to Write a Great Software Test Plan” by Robert Japenga on the MicroTools Inc. website.
http://www.microtoolsinc.com/howstp.php
“Why do we write a test plan?” by Ainars Galvan in his blog on the testingReflections.com website. (Sept 2007)
www.testingreflections.com/node/view/5144
Test report
A test report is written by the individuals who tested the product. It identifies the findings and recommendations to fix bugs and suggestions to correct product defects. The test report should be detailed enough to be useful, but not so thorough that no one outside the test group will understand it. The test report identifies the tests conducted (e.g. integration testing, unit testing, and user acceptance testing) and results.
Without a test report, the project team does not know what features and functions were tested and the results, and recommendations for correcting problems in order to qualify the product for delivery to market or implementation.
Suggested resource: “Dimensions of a Good Test Report” by Michael Kelly on the informIT website. (Mar 2006) www.informit.com/articles/article.aspx?p=457506&rl=1
Meeting minutes
Meeting minutes are the hallmark of a well-run meeting. They provide a record of date and time of the meeting, topics discussed, decisions, open issues and action items. Minutes provide useful information for people who did not attend the meeting and written record of the proceedings for attendees. Meeting minutes should be written immediately at conclusion of the meeting while the information is still fresh in everybody’s mind, and archived in a location that is accessible to members of the project team.
Without meeting minutes, the project team has no record of discussions, decisions, open issues or action items.
Suggested resource: “Taking Meeting Minutes” by Dawn Rosenberg McKay on the About.com Career Planning website. http://careerplanning.about.com/cs/communication/a/minutes.htm
Leave a Reply
You must be logged in to post a comment.
Connect With Us Online
Our award-winning Phoenix chapter provides industry support, education, community service, and networking opportunities for chapter members, students and local businesses.
Learn more