Table of Contents
Why do we need documentation?
Let’s start from the beginning. What is the documentation for? I once heard such a wise sentence “We sign contracts for bad times.” The same is in part with the documentation of information systems. It is a form of contract between businesses and developers. In the customer-supplier relationship, it is also the basis for the contract settlement with the customer. We check whether the product we received at the end is consistent with the documentation.
Documentation is something that we only feel when the problems begin. Because as long as it is fine, no one thinks about it. After all, everything somehow goes on without her.
Why document a project?
- The documentation defines the scope of the project. Consequently, it is the basis for the settlement with the client. A well-defined scope increases the chance of a customer being satisfied with the project.
- Documentation speeds up work and reduces changes. We don’t have to ask about everything; we have the most important things settled before starting the task.
- It is cheaper to make changes “on paper.” Introducing changes to the documentation costs much less than changes to the finished product and are possible much earlier.
Does every project need documentation?
In public projects or in large tenders, the documentation is more formal. Often, its scope, types of documents, and even their templates are specified in the contract. Apparently not, but yes But it will not look the same in every project. It will be rather extensive, often broken down into different types of documents describing the system at different levels of detail (e.g., separately at the business level and separately at the more technical level).
However, documentation is not always bloated. In Scrum and Agile in general, the role of documentation is played by, for example, User Story. There, users’ expectations towards the system are described.
On the third hand, we still have small projects, e.g., website implementations, where the documentation can be considered as the listed scope (e.g., a list of subpages) and a graphic design.
It all depends on the scale of the project and what mode of work we will adopt with the client.
What should the system documentation describe?
Documentation at the business level should describe the users’ expectations towards the system (requirements) and the key information on their implementation at the technical level. It may contain a system architecture design, technology description, GUI design, or, for example, a description of the adaptation in the case of implementing a ready-made product.
What can be documented in the project:
- User requirements and the manner of their implementation
- Description of the system architecture
- The scope of processed data
- Description of the technology
- The course of business processes
- GUI design
- Description of the system adaptation in the case of pre-implementation analysis of the finished system
- Data structure
- Integration between systems
- Test cases
Methods of documenting systems
Most often, in addition to the so-called verbal and musical description, UML diagrams (e.g., use case, sequence, class diagrams) or BPMN diagrams are used to document the systems when we need to document the process.
We will document the reporting system; differently, one based on ergonomic GUI, and we will describe complex processes in the company differently.
The use of diagrams is not necessary. The manner of presented information must allow for an unambiguous understanding of all project stakeholders. If, instead of a complicated diagram, it will be easier to make a sketch or a screen layout – then let’s do it.
Does the project manager have to be able to create documentation?
Typically, an analyst creates the documentation (or someone with a similar role, e.g., Product Owner creating stories). We often distinguish between business and system analysts.
Of course, the project manager does not have to create documentation. But let’s face it – the analyst will not always be available; sometimes, in smaller companies/projects, the role of the analyst and PM are combined. I think that the PM should at least understand the documentation to the extent that he can talk about it freely with both the client and his team, even if he is not the author of it.
Also Read : The 5 Best iPhones of 2021
