A software project is defined, for the purposes of this blog entry, as a set of people working to produce a new software system, or to modify an existing software system.
The result (exit condition) of a software project is a set of artifacts and other assertions:
- Document (or wiki etc) describing what the software should do, i.e. requirements. This will include subtle details, about what the system does, that will not immediately be obvious by looking at the front-end, or reading software design documentation. This should be a complete description, which is useful for the future, not just a “delta” from the last version.
- Software architecture documentation, in words. Simply looking at 1,000 Javadocs will not enable a new team member to understand the system. Documentation should also include which other options were evaluated and not chosen, and why, to avoid future teams considering the same things.
- (Obviously) the source code for the software. Including the front-end, back-end, any HTML, etc.
- Unit test scripts for all back-end classes needing them.
- Front-end tests. Either a document (simple statements such as “Click on Submit without enough money on account. See error message”), or configuration of a front-end testing program.
- Performance tests done and the software to perform them, if appropriate.
- Configuration (or creation) of a monitoring system to monitor the system once it’s live, if it’s a service (e.g. web site).
- Administration system for customer care, if it’s a service.
- Management reporting. Especially just after a system goes live, management are always very curious about key statistics, such as number of users, number of items sold etc. That needs to be analyzed in advance and the system in place when the system goes live.
- Class diagrams
- Javadoc to describe the purpose of individual classes and methods (where this is not obvious from the names). For scripting languages: parameter and return types (as this cannot be deduced from the source code).
- If this is not the first version of a system, migration concept including scripts to install software, migrate schema, filesystems containing user data, and anything else.
- System uses appropriately international character set such as UTF-8. (This is not particularly modern, the WinNT team decided to do this in 1988.) Java does this out of the box, but it’s more than just the programming language. This includes any database, any data stored in flat-files, any APIs (within the system or to/from external systems), and so on.
- All of the above under version control
- Not only the software installed on a live system, but also the existence of test and staging systems. If one uses the live systems for testing, then, once one’s gone live, one has no way to fix bugs in a testing environment. And bugs will happen, and they need to be fixed fast, so one had better have thought of this in advance.
- Bug tracking, or wiki system, or some way that the team is trained and rehearsed in using, to track and assign errors as they occur.
- Understood and tested data backup and recovery process. (What happens if the live DB crashes? Better have thought about recovery before that happens.)
- The team must sleep e.g. 2 days before a release. After a release (bug fixing) is the most stressful time of a project and where the team must be at its most alert (as fixing is time-critical). It’s important to sleep beforehand, and not e.g. work 7 days a week then in the evening finally release, then go to bed. (You can be certain that 1 hour after you’ve gone to sleep the site will be offline due to some problems, and you weren’t there to fix them.)