Lesson Three: Requirements and Design Documents
Program documentation comes in many forms and is used to help create programs with the correct behavior. This is especially important when working with a team, where individuals need to deliver parts of a program that work together. Good documentation also helps you remember how and why code was written. If you or a team member need to make changes later, you can use the program documentation to help ensure your changes are aligned with the program's goals and don't break anything else.
Software engineers working on the requirements phase of the SDLC should produce a requirements document that describes the program to be written. Similarly, the design phase should result in a design document that gives guidance to programmers who need to write the program code. In this lesson, we'll explore the contents of these two documents in more detail.
Understanding the Problem
Before starting detailed work on a program, it is important to understand the problem you are trying to solve. More effective software programs can be written by those who understand a problem's purpose, description, and goals.
Purpose - Ask yourself why this problem exists and what needs to be solved. For one example, we know that unsafe driving can lead to accidents, so society might want people to drive more safely on the road. In another example, we know that when humans type text into a document, spelling, grammar, and other types of errors may occur. We may want to improve the overall accuracy of the text that we type. Understanding the essential purpose can guide your remaining efforts to solve a problem.
Description - Based on a problem's purpose, we can develop a high-level description of the problem. A description like "automatically detect and warn drivers when they approach a stop sign" or "detect and correct spelling errors in a line of text" will help focus your initial investigation.
Goals - What is the end result of solving a problem? Are there observable or measurable goals you can identify that, once reached, will solve the problem? For example, a goal might be to reduce the number of accidents at 4-way stop signs or eliminate spelling errors in written text.
With these three key factors in mind, software engineers can begin the process of defining a program to solve the problem.
Initial Investigation
The major requirements for a program are often discovered with an initial investigation. This investigation involves research to see what kind of program should be made and the main features users want to have in the program. Research is normally done with users who are likely to use the product. Data can be gathered in many ways.
| Approach | Description |
|---|---|
| Brainstorming | A brainstorming session allows everyone involved to quickly suggest and explore key ideas and features. |
| Surveys | Surveys ask users about their desired features or experience using any type of question-and-answer mechanism (online survey form, physical survey, etc.). |
| User Testing | Users can be invited to explore or test a prototype of a proposed program. Often, giving users an early look at a product will help focus the requirements and design on areas of importance to users. |
| Interviews | Asking a user to discuss the needs for the program in a live, face-to-face, or online interview can provide great details and ideas that may not be easily communicated on a survey form. |
| Direct Observations | If you are trying to solve a problem for a user, try observing the user while he or she completes (or struggles with) the task without your proposed program. Based on your observations, how can your software help make things easier? |
The initial investigation should produce a clear description of the problem to be solved, including the program's purpose and goals.
Requirements Document
A requirements document is intended to guide the overall project. Your resulting document might include information such as:
- A broad description of the overall goals of the software program. What is the purpose of writing the code?
- A description of the major program flows or user tasks, often in a graphical storyboard or map
- Specific features and behavior required by the customer or user
- A description of the inputs and outputs of the system
- For a console program, this may include a sequence of messages that the user will see, the input gathered from the user, and the resulting output.
- For graphical user interfaces, this may include sketches of the envisioned screens and controls, user feedback, and a description of key user actions or workflow through the system.
- Inputs and outputs may also include files used to import or export data, network protocols used to send or receive data, etc.
- A description of the processing to be carried out against data managed by the system
- Expectations for performance (speed) and the amount of data that can be handled successfully
Once your team has produced a detailed requirements document, they can confidently begin designing the program to meet those requirements.
Design Document
A design document can detail exactly how the program code will be written. The design document is normally based on a requirements document. it is often written by an experienced team member with good communication skills and an understanding of the technology and program to be written. Design documents often contain these points:
- Overview and background - is there anything the reader needs to know that isn't already in the requirements document?
- High-level design - may include decisions on things like:
- What programming language will you use?
- What other technical tools and libraries will be useful?
- What are the main classes and how do they relate to each other?
- What kinds of data need to be managed and how will it be stored in your program?
- Detailed design - for each class or sub-system, answer questions like:
- How will data be received and communicated between classes?
- What are the significant methods and properties of each class?
- How does the program flow and what logical decisions need to be made?
- How is user input received and how is data displayed to the user?
- What algorithms or formulas need to be run against your data to produce results? How will those algorithms be implemented in code?
- How will your program respond accurately to boundary conditions or unusual input data? How will it validate all input data before beginning processing?
A design document may also specify areas where the code or team members will rely on some external tool or team, the overall order in which things will be done, certain milestones where the program should have minimum features ready to test, etc.
Large programs may need more than one design document at different levels. High-level design or architecture documents can specify how major sub-systems will work together. Lower-level design documents can detail exactly how a specific sub-system will be created.
Document Formats
Successful requirements and design documents will communicate their ideas effectively to the programmers and other team members that need to use them. Sometimes, these documents use an elaborate, formal style with many sections. In other cases, more informal versions are an appropriate solution.
In many cases, requirements and design documents will need to contain drawings, pictures, and tables. Therefore, you normally want to use a word processor or similar software application that can produce these kinds of media-rich documents. Simple text editors can't embed complex information. If needed, you can even write your documents by hand on paper.
When producing your own documentation, the exact format is up to you. You may select any available word processing or text program that meets your needs. Your teacher may specify a particular type of program and certain content or styles that must be present in your document.
There is no single, universal standard for how requirements and design documents must be written. Companies will often have their own templates to specify style and content. This discussion demonstrates typical contents for each kind of document. We provide sample templates, but your teacher may specify any format for your own work.
Sample Documents
We have created the following templates for requirements and design documents that you may choose to use and modify for your own projects. They are available in .RTF, .DOCX, and .PDF formats. Your teacher may give you guidance on whether or not to start with these templates or create some other format on your own.
Click on the link(s) below to review our sample templates.
Remember, these documents can be used as a starting point or guideline, but your final results can be completely customized to meet your needs.
Other Program Documentation
Requirements and design documents are separate from your code and are generally written before you start coding. However, as you write your code, you should continuously provide additional documentation that details exactly how each part of the code works. In a collaborative team, over time, many individuals may be responsible for reading, understanding, and changing your original code. This extra written description of a source file, function, or other pieces of code should explain to other developers (or remind yourself) exactly how the code works.
In Python (and most other text-based languages), program documentation is easily added with comments in the source code. The comments provide human-readable information about the code without changing the program's behavior. Consider the comments in the example code below.
# Author(s): Worker Bee 1, Worker Bee 2
# This function will take in input list of integer values
# and returns a list with those values sorted in ascending order.
# This code was adapted from the Bubble Sort algorithm described by Sheer Genius at:
# https://www.example.com/python/algorithms/BubbleSort.html
def sorting_algorithm(inputList):
# line-by-line comments
Python comments start with a hashtag symbol (#), and everything to the right of a hashtag is ignored when running the program. At the top, these comments describe the overall purpose of the sorting_algorithm() function and describe the function's input and output data. Inside the method, the programmer can leave detailed, line-by-line comments, where needed, to explain how each line works.
Notice there are comments that also show the name(s) of the developers who originally wrote the source code. This is similar to an artist signing a painting, but the author names are also important sources of information for other developers. If a team member is assigned to make a change to the original code later and has a question, the original author(s) could be contacted for clarification.
Finally, because this example code was based on the work of someone else, the comments also include a citation for the original author of the algorithm and a link to the website where that original work was found. Not only does this help provide credit to the original author (and may be required to meet licensing agreements), but it gives other developers somewhere else to go for help and additional context about the source code.
While text-based languages like Python are easy to add comments to, other "blocky" languages like Scratch may not allow programmers to insert human-readable comments within the source code. In that case, you would need to write out program documentation in some other way, such as in a text file or word processing document that you store alongside the source code or in a repository designed for that purpose.
Work with Me: Preparing to Write
This chapter is all about creating your own unique project (in a team or as an individual). As part of the project activities, you will be asked to create your own requirements and design documents.
Take some time now to review our template documents (linked above). With your teacher, discuss the document formats and styles that you will use for your creative project. Answer these questions:
- Which word processor or software program (if any) will you use to create your documents? Or, will you create paper documents by hand?
- What is the resulting file format of your documents and how will you submit them to the teacher?
- Are there any specific pieces of information your teacher wants you to add (or omit) from your documents?
By working out these details in advance, you'll be ready to go when you are asked to start writing your own documents.