IT Project Documentation Best Practices are not simple because the purpose of the documentation is not always obvious. First, in an IT project, you can find a lot of different documentation; the famous user manual, the requirements documentation for the software operator, the architecture and design documentation for analysts, designers and developers and the technical documentation or software documentation for programmers are the main ones examples.
In short, Documentation is like insurance, you need it but you must find the right balance.
As far as we are concerned, we will talk about the architecture and design documentation and the technical documentation of an IT development project. So, what should we document?
In this series of posts, we will address the following points:
- What should be documented in an IT project?
- How should we document it?
- Where should these documents be made available to different readers?
What should be the object of an IT Project Documentation?
To determine what needs to be documented, consider:
- what must be delivered; application
- the different stakeholders
- the environment
The steps of a software project are generally the same, regardless of the project:
- Planning (Releases and Sprints)
According to these steps, the potential documents of an IT Project Documentation to be delivered are:
First, before starting an IT project, normally the company will have several documents:
The standards of the organization
- The nomenclature
- How to name objects
The design and implementation standards (coding) of the organization
- The development architecture
- Definition of “layers”, classes, methods etc.
- How to name objects
- Test standards
For the project itself, we have a panoply of potential documents to produce. We will associate these with the different stages of the software development process:
- In this phase, we include the various meetings needed to understand the client’s request. A meeting report must necessarily be produced after each meeting. This should contain the following elements:
- The subject (s) of the meeting
- Person (s) by subject
- Objective (s) of the subject: Information, Exchanges, Consultation, Generation of ideas, Decision
- Maximum duration
- Report: Report and decision (s) on the subject
N.B. The treatment of “To Do” of these meetings will be discussed in another ticket
- The functional specifications document is definitely one of the most important documents. It translates the client business needs into requirements for developers. Depending on the size of the deliverable, it may be very short or very long, but it is always mandatory.
At Analystik, the functional specifications document is all the more used as we feed it throughout the different development stages with technical specifications.
At Analystik, the functional specifications document covers the following elements:
Business Requirements (BR)
- Objectives of the project
- Business requirements
- Business requirements excluded from the scope of the project
Functional Requirements (FR)
- Objectives of the deliverable
- Functional Specifications
- Functional requirements excluded from the scope of the project
- At Analystik, planning is executed with Microsoft Team Foundation Server (TFS) Cloud. All the documentation produced is found in this tool. It will include Epics, Features, User Stories and Tasks. The beauty of this tool’s Cloud version is that all project stakeholders have access to it, including clients.
- A good practice is to get developers to take the time to design the functionality they must deliver before they start coding. Often at Analystik, this takes the form of UML schemas like this:
- For development, in the best of all worlds, the first document to be produced would be the Test Plan of the functionality to be produced.
On the other hand, let’s be honest, as long as a Test-Driven Development culture is not fully implemented, the Test Plan is often produced later in the process.
- The other documentation to be produced is not a document but a documentation included in the code. Yes, yes, we are talking about COMMENTS!
Unfortunately, it’s difficult to talk about good business practice because the quantity and quality of comments have always been depending on and will always depend on the personality of the developer … despite code reviews and other validation mechanisms.
For each feature, it is necessary to define the objective of the test, the steps, as well as the expected results. Our test plan grid looks like this:
- Again, for deployment, the documentation can be minimalist such as a simple website or very complex; for example, a critical Windows application deployed on hundreds of workstations and heterogeneous environments.
In this latter case, we will have several tests phases; different “Quality Assessment” environments and follow-up tools will be used to compile and follow the tests, tools like Team Foundation Server Cloud, JIRA, etc.
Of course, depending on the application to be delivered by the various parties involved, and the environment in which the application will be running, a variety of other documents may be required. Here are some examples:
- Project plan
- Daily Scrum – Obstacle Tracking
- List of actions to follow
- Tracking hours and amounts
- List of deliverables
- Follow-up on the quality assurance of deliverables
It is therefore important to find a balance with your documentation because, unfortunately, it is not free and its cost can vary from 10% to more than 100% of development costs.
The following benefits of the documentation of a software development project must be pointed out though:
- Improved durability of the application delivered by facilitating its evolution (upgrade)
- Facilitates support (troubleshooting)
- Minimizes business risk at multiple levels by giving the enterprise some autonomy with regards to its IT development team or IT vendors
On the other hand, the documentation of an IT project lengthens the time and development costs.
Happy Development Project,
Denis Paul & Michel