About the Author
David Dick is an Associate Fellow and member of the Washington D.C. Chapter.
|
STC UUX Community Newsletter |
 |
| Usability Interface |
Should Technical Writers Write System Requirements?
By David Dick
What do you do when the user guides and help files have been written: sit on the bench and wait to be told to find billable work? If you want a challenging opportunity to put your skills to good use, I encourage you to volunteer to help the project team document their system requirements (also referred to as “software requirements”).
Many project teams do not have enough staff to write and manage all documentation required by the Systems Development Life Cycle such as software requirements, functional requirements, design specifications, and test reports. Short development cycles force software project teams to quickly design, test, and release the product. The solution is to hire a technical writer to help in the area of development documentation.
In May 2006, I was hired by a technology services company to support a project team come into compliance with a client’s software development life cycle, teaching developers the principles of documenting product design and documentation management. In my spare time, I documented the design of several legacy systems. Six months later, I was asked if I would like to write system requirements: I eagerly accepted this new challenge. This article details what I learned about writing system requirements.
Do You Have the Right Skills?
When asked if I was willing to write system requirements, my first thought was, “I don’t have the right skills to write system requirements.” But soon became obvious to me that I did possess the essential skills and experience to write system requirements. It’s quite possible that you do too, according to Donn Le Vie, Jr. in Writing Software Requirements Specifications.
Le Vie lists three essential skills that make technical writers ideally suited for the task:
- Technical writers know how to determine the questions that are of concern to users regarding ease of use and usability.
- Technical writers can then take that knowledge and apply it not only to the specification and documentation development, but also to user interface development, to help ensure that the user interface models the customer requirements.
- Technical writers involved early and often in the process can become an information resource throughout the process, rather than an information gatherer at the end of the process.
Most organizations have templates for writing system requirements, and completing them is straightforward. Good structure and layout is the first step of well-written system requirements and an important contribution of the technical writer.
Asking the Right Questions
A common mistake of collecting requirements is to ask the client, “What do you want the system to do?” The client replies with a litany of features and functions. This is not an ideal way to capture requirements, and certainly not an ideal method to understand the characteristics of the intended system. The correct method to collect requirements is to understand the behavior of the system in order to identify a sequence of actions between the system and the user.
Many organizations have their preference for performing systems analysis. I can only tell you about Use Cases. A systems analyst is teaching me how to create Use Cases and how to translate them into system requirements. U se cases provide scenarios that convey how the system should interact with the users, called “actors”, to enable them to achieve a specific business goal or function. Creating Use Cases help developers to understand operational scenarios; inputs, outputs, interfaces with other systems; and user roles and user classes.
The Importance of Good Structure and Layout
Getting started in writing system requirements may begin by reviewing requirements for grammar and format. That’s how I got started, and it afforded me an opportunity to ask questions of an experienced systems analyst. Fortunately, the client has a template for system requirements. However, if neither the client nor the development team has a template, I have learned that it’s easy to create. The IEEE Standard 830-1993, Recommended Practice for Software Requirements Specifications, is an ideal source for understanding good structure and layout, and includes templates for structuring the content.
The Writing Style
The writing style and language of a system requirements specification merits a study all its own. The writing style system requirements specifications must be exact, without ambiguity, and precise because other project documents depend on it. A well-formed requirement identifies a system 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.
Most organizations have a style guide for writing system requirements specifications. Donn Le Vie’s article Writing Software Requirements Specifications provides helpful suggestions on language, tone, and how to phrase statements. By learning the techniques to write system requirements, I can provide developers with the details they need to understand fundamental requirements, measurable qualitative and quantitative attributes and characteristics, and boundaries and limitations.
The Importance of including Usability in System Requirements
The common concerns of technical writers are the problems caused by complicated products, and user guides and help files that serve as a suboptimal solution to poor product design. If usability is a criterion for product success and successful user adoption, then system requirements should address usability issues.
Because usability tends to be in the eye of the beholder, specifying usability can be a formidable challenge. Everybody wants a product that is easy to use. However, a system requirement such as, “The system shall be easy to use” is of no value to a developer because it’s not specific, not measurable and not traceable. That’s why it’s important to consider usability as all the characteristics that make a product easy to use, easy to learn, and easy to maintain.
Identifying the context of use helps to establish measurable requirements that can be evaluated during usability testing. Identifying external interfaces (i.e. all inputs into the system and outputs from the system). Identifying measurable performance goals. These are just a few examples to consider when including usability in system requirements.
Treating the Systems Requirements Specification as a Document
The systems requirements specification is a document that must be reviewed, approved, updated and accessible.
Sometimes the systems analyst will organize meetings to review the software requirements specification; otherwise, I must organize them. These meetings are no different than reviewing a user guide. For example, I distribute the document for review, I organize meetings with reviewers to capture the recommended changes, and I organize meetings to discuss the changes with subject matter experts and project stakeholders.
The system requirements specification is a contractual agreement between a customer and vendor. For this reason, it must be approved by the person requesting the system, the project manager, the budget holder and the system owner. Some options for capturing the approval are e-mail and retaining a copy of the signed signature page.
When the systems requirement specification is approved, I archive it in a documentation repository that is accessible to the project team. Previous versions (drafts) can either be archived or deleted. I retain copies of documentation reviews.
Managing Changes
The systems requirement specification is an ever-changing document and that is why managing changes is an absolute necessity. The scope of my effort is to collect requirements, not update them. Maintaining requirements is a challenge in any environment that does not adhere to a waterfall development approach. When I am asked to assist with updating requirements, I follow the organization’s policies and procedures to gather changes from users and system owners, and communicate changes to stakeholders.
Conclusion
Since my transition from writing user guides to documenting system requirements, I am learning how to create use cases and how to translate them into software requirements, and how to facilitate development meetings. In the meantime, I educate system developers on the principles of documentation management, and they teach me the principles of software design. I enjoy the new challenges, my new role, and the opportunity to apply my skills to help ensure successful product development.
Learning how to write system requirements have given me greater understanding of the system development process. I am putting my understanding of task analysis to good use to assure well-defined and well-written requirements. My first performance appraisal indicates that I am making very good progress, and the developers consider me an asset to the team. Taking on this new opportunity and doing well, is proof that I can do more than write great user guides. Are you ready to challenge your knowledge and experience?
Resources
Recommended Practice for Software Requirements Specifications, IEEE standard 830-1993, December 2, 1993
Clinger-Cohen Act (Information Technology Management Reform Act of 1996)
Software Requirements: Objects, Functions, and States, David, Alan M. 1993. Englewood Cliffs, NJ: Prentice-Hall
Managing Software Requirements, A Use Case Approach, Dean Leffingwell and Don Widrig
Writing Software Requirements Specifications by Donn Le Vie, Jr.
Understanding Unified Modeling Language (UML) to Create Use Cases.
 |
|