You have probably heard before how important it is to plan a software solution before beginning its implementation. If nobody told you, here it is: it is EXTREMELY important to plan before you implement. That’s a rule applying to every software development and integration. What do I mean by plan exactly; well one major facet of planning that is often overlooked is the documentation of the project. The biggest challenges with documentation is that the documents often get out of date, people often see documentation is an overhead and a waste of time and money, and project managers may lack experience in implementing applications and don’t know which documents are required.
I am including here a list of some of the documents you should be asking for if they are relevant to your project:
Business Requirements
This document defines all the requirements of the application; everything that the application needs to be able to perform. This is important because acceptance testing is based on how the application performs in relation to its requirements.
Technical Requirements
This document defines technical requirements for the application such as security, response time, etc.
External (functional) Design documents
These documents are probably the most important documents of all. They describe how the application works, what it does, the logic involved, flow charts, and all elements (rules, formulas, lookup tables, rate tables, hierarchies, etc) used to implement the compensation plan.
Internal (technical) Design documents
These documents elaborate on the functional design documents and describe technically how the application will work. Programmers use the technical designs to develop the application. The level of detail should be such that the programmer’s role is only to code what is specified in the document, leaving little for the imagination (i.e. variable names, database objects, etc should all be specified).
Change Request document
It is important to obtain all change requests since the initial requirements in order to understand the current state of the application.
Quality Assurance Plan
This document describes in detail how the application is being tested. It illustrates how different test phases will be performed. Some of these phases include unit testing, system testing, integration testing, and regression testing.
Test documents
Test documents consist of detailed test plans for each test phase described in the quality assurance plan. There should be detailed steps on how to perform every scenario being tested. Test data used for testing should also be provided and documented
Programming/Customization guidelines and standards
A set of guidelines, rules, standards and best practices used when developing the application should be provided.
Data models of databases
The data model shows the relationship between all database tables and attributes. In the case of the implementation of a packaged solution, all custom tables and custom fields should be documented.
Data Dictionary
The data dictionary should include a precise definition of data elements, user names, roles and privileges, Schema objects, Integrity constraints, stored procedures and triggers, and general database structure. In my opinion this is one of the most important document in a project with a heavy data integration component. The definition of the data elements should explain what the element is, where it comes from, how it is generated, what is its general structure and type, list exceptions, etc.
Deployment Procedures
The deployment procedures document describes the method for deploying the application. In the case of a packaged solution, it should list the correct files and versions to deploy, as well as any dependencies or order requirements.
Today I came across a web forum called “Ask Jon!” by OpenSymmetry. It’s a great knowledge exchange platform where anyone can submit questions and answers.
Julienldionne's Weblog 