If the software is a first release that is later built upon, requirements documentation is very helpful when managing the change of the software and verifying that nothing has been broken in the software when it is modified.
Traditionally, requirements are specified in requirements documents (e.g. using word processing applications and spreadsheet applications). To manage the increased complexity and changing nature of requirements documentation (and software documentation in general), database-centric systems and special-purpose requirements management tools are advocated.
A good architecture document is short on details but thick on explanation. It may suggest approaches for lower level design, but leave the actual exploration trade studies to other documents.
A very important part of the design document in enterprise software development is the Database Design Document (DDD).
It is important for the code documents associated with the source code (which may include README files and API documentation) to be thorough, but not so verbose that it becomes overly time-consuming or difficult to maintain them.
Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class.
Introduced by Donald Knuth.
Literate programs are written as an uninterrupted exposition of logic in an ordinary human language, much like the text of an essay, in which macros are included to hide abstractions and traditional source code.
Comparison to well-documented code. Well-documented code or documentation extracted from code follows the structure of the code, with documentation embedded in the code; in literate programming code is embedded in documentation, with the code following the structure of the documentation.
CoffeeScript supports a "literate" mode, which enables programs to be compiled from a source document written in Markdown with indented blocks of code.
Elucidative Programming is the result of practical applications of Literate Programming in real programming contexts. The Elucidative paradigm proposes that source code and documentation be stored separately. This paradigm was inspired by the same experimental findings that produced Kelp.
Often, software developers need to be able to create and access information that is not going to be part of the source file itself. Such annotations are usually part of several software development activities, such as code walks and porting, where third party source code is analysed in a functional way.
Typically, the user documentation describes each feature of the program, and assists the user in realizing these features. A good user document can also go so far as to provide thorough troubleshooting assistance.
There are three broad ways in which user documentation can be organized:
- Tutorial: A tutorial approach is considered the most useful for a new user.
- Thematic: A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user. Some authors prefer to convey their ideas through a knowledge based article to facilitating the user needs.
- List or Reference: The final type of organizing principle is one in which commands or tasks are simply listed alphabetically or logically grouped, often via cross-referenced indexes. This latter approach is of greater use to advanced users who know exactly what sort of information they are looking for.
- TDD: technical design document
- CRD: Customer Requirements Doc
- PRD: Product Requirements Doc
- requirements lists, functional designs, user stories, graphics design mockups, usability studies, UML diagrams, business process diagrams, data model specifications
Why writing them?
As the adage goes, "If you fail to plan, then you plan to fail."
- Express the developer's thought process during the design phase.
- A good design document minimizes unexpected complications by addressing them before the code is written.
- Good for peer developers, and thus for company/organization. A well written design document is one of the most valuable tools a successor developer can have when entering a new project.
- A design document is a way for you to communicate to others what your design decisions are and why your decisions are good decisions.
- A document will provide you, your manager and your team with a common vocabulary for talking about the project.
- The design document is a written contract between you, your manager and your team. Obviously, requirements are going to change sometimes, but with a baseline document you have the power to say that no change in scope is due to a misunderstanding of the requirements.
What makes a good doc?
The biggest factor that determines if your design document is good is whether or not it clearly explains your intentions. This presents a problem, however. In order to convey design decisions, you have to consider the audience that you are writing for. Therefore, you need to prepare two versions, one for peer developers, and the other for your managers.
- You should be able to list at least one compelling reason, related to the requirements, for why a design decision was made.
Diagrams are a great tool for visualizing your design, but they cannot convey the motivation behind your design decisions. That is why it is so important to let diagrams supplement your design document, not be your design document.
- Any associated risks must also be documented. By listing the benefits you give your manager tangible items that describe why your design is sound. By documenting the risks of your design before development, you pass the responsibility of that risk to your manager, which is where it belongs.
Writing for peer developers
The goal of a peer developer design document is to make sure that your ideas are valid and that your approach works with what others are doing.
- Section 1 – State the purpose of your project/sub-system: write a few paragraphs that describe what the project or sub-system does.
What is the problem it is trying to solve? Why does it need to exist? Who will use it?
By answering these questions, you establish the scope of your design. If you find it hard to write a few paragraphs in this section, then you probably don't understand the domain as much as you should. If you can't fit your description within a few paragraphs, then perhaps the scope is too large. Use this section as a tool to verify that the scope of your design is reasonable.
- Section 2 – Define the high level entities in your design: High level entities are objects, or groups of objects, that constitute major constructs of your design.
Good examples of entities are a data access layer, a controller object, a set of business objects, etc.
Explain in a few sentences what each entity does. The descriptions don't have to be verbose, just enough to explain what each block's purpose is. Be sure to describe your reasoning for defining the entities in your diagram and what their roles are.
- Section 3 – For each entity, define the low level design: This section is where your objects and object relationships are defined. For each object (or set of objects) define the following:
Describe in a paragraph how the object is used and what function it serves.
If an object will interface with an external object or system, it is a good idea to show the interface for the object.
Most importantly, you must again describe your thought process for defining the object as you did. List the benefits and risks. If an object provides an encapsulation, describe in a sentence why the encapsulation adds value. Use your descriptions to give meaning to the diagrams. They don't have to be verbose, just enough to get the point across.
If your object needs any special configuration or initialization, this is a good place to describe it. If not, this section can be left out.
- Model. May include UML class diagrams.
- Interaction. May include UML sequence diagrams.
- Section 4 – Benefits, assumptions, risks/issues: In this section, make a list of 5-6 top benefits of the design, a list of ALL known risks/issues and a list of ALL assumptions.
Some of this may simply be rehashing what you wrote in a previous section of the document. What's important is getting all of these items into one section so that the reader doesn't have to read the whole document to understand what the benefits, risks and assumptions are.
Never remove anything from this section! As risks become non-risks, document that they are now non-risks and why they became non-risks. Never erase them from the document. The same holds true for assumptions. You should be able to look at this section and know instantly what the current risks are to your design.
Writing for a Manager
The goal of a design document for your manager is to make sure that your manager understands what the main entities of the system are, what the benefits are and, most importantly, what the risks are. The document is your chance to show that you understand the requirements and that you have come up with a plan to meet those requirements.
If you have written the peer developer document well, then writing the manager's document is simple, because it is just made up of sections 1, 2 and 4. By dividing the peer developer document up as described previously, the parts which are typically not meaningful to a manager have been contained in a single section of the document which may be removed.