Documentation
Basic documentation facilitates the transfer of knowledge and helps developers stay focused on the tasks at hand. Not only does documentaion identify what needs to be done and why, it also identifies approaches that have been precluded and the decisions related to that.
We take a fairly relaxed approach on documentation, as developers hate to write it, and everyone hates to read it. We still try to always include some core elements, like a Vision Document for most major projects, a Domain Model (often considered a secondary artifact of the Requirements Specification and/or Software Architecture Document) for pretty much all projects and a Software Architecture Document for more complicated projects.
All documentation is expected to be nearly as fluid as the code. Changes in the code will usually represent changes in the understanding of the requirements for a project, and thus should cause appropriate changes in the documentation to recognize and account for these changes. Similarly, high level discussions that lead to changes in the Documentation should dictate changes in the code. These changes can be directly identified given the process followed in the code development (See the SoenEA Thesis). For example, a change in Requirements might lead to changes in the Use Cases, which would lead to changed in the Testing (part of the code base) (addition/modification of tests) which would lead to changes in Dispatchers (part of the code base) which correspond to those Use Cases. Other changes in requirements might reflect changes elsewhere in the code, but this will primarily result in either a change to the code, then subsequent testing, or a change in the testing and then subsequent changes to the code.
Below is a breakdown of the documentation we consider:Vision Document
A Vision Document should provide overall guidance as to the overall purpose of a given project. It will identify similar products, outline high level goals, describe important stakeholders and apply scoping. In particular, the Vision Document should track who has added or removed what high level goals, and at what point such a thing has happened during the project.
Use Case Model
A Use Case Model (UCM) will visually describe the Actors involved in using the system (e.g. varieties of administrators, guests and users), outlining a basic set of roles and associated functionality (the Use Cases) in the system. The Use Cases themselves will be textually desceibed to outline expected behavior of the system and how to address exceptional scenarios (e.g. a user logging in with a wrong password).
Software Requirements Specification
A Requirements Specification will outline non-functional requirements, focusing on performance, security, reliability and other similar concerns. These requirements can then be cited in other documentation as the primary means of deciding on technical approaches or determining correctness. A Requirements Specification may also outline functional requirements seen in the UCM, or even some beyond those outlined in the UCM.
Software Architecture Document
A Software Architecture Document (SAD) will describe various aspects of the architecture by means of views. These views will highlight architecturally significant Use Cases, important algorithms, third party systems used, architectural and design patterns and the physical/resource distribution of the system.
Story Boards
Story Boards will provide a quick reference to the planned visual layout of the project, if there is one. Design features, organization of menus, logos and navigation will be depicted. As well, interaction will be described via associations with Use Cases in the UCM.
Traceability Matrix
A Traceability Matrix links elements of the other documentation together to provide a quick overview of how they relate. This includes such things as which tests are associated with which Use Cases or Requirements, which Requirements are associated with which Use Cases and often which Use Cases are associated with given Storyboards. This provides needed traceability to help documents stay synchronized.
Test Plan
A Test Plan will outline tests to be applied to any prototypes or development/production implementations. The common tests to consider in this forum of documentation are:
System level
These tests imitate how users will interact with the system. They are slower, but most accurately reflect the use of the system, and are less affected by changes underneath the hood of the application.
Regression
These tests are created to test against discovered defects and to ensure that they are resolved and do not come back. These tests are quick to run, but often overlap with other tests as they highlight blind-spots.
Unit
These tests are applied to individual modules, testing them in isolation. These are quick to run and write, but are brittle and must be updated often.
Acceptance
These tests involve scripts that a person uses to manually walk through the site to visually test how it behaves. These are the slowest tests to "run" as they are the only non-automated tests. However, they are the only means of effectively catching UI defects and are a significant aid to usability and quality assurance.