Documentation in IT projects is a topic that often raises questions and doubts among clients. What exactly is “documentation”? What are its types? Is it an additional cost? Will it ever be useful? Where can I find it? In this article, we answer these questions (and more).
What is meant by the word “documentation” in IT projects?
Documentation in IT projects encompasses a variety of different documents. There is no single “documentation,” which is why it’s important to know all its types and be able to distinguish between them.
In this article, we’ll explain the four most important types of project documentation. In short, they are:
- Functional Documentation – defines how the software should function and look.
- Technical Documentation – specifies the technological solutions used and how to utilize them.
- Testing Documentation – facilitates the planning, execution, and analysis of tests.
- User Documentation – explains to the end user how to use the application, often referred to as a user manual.
Types of documentation in IT projects
1. Functional Documentation
Describes how the application should function and look from the perspective of end users.
This type of documentation is created during the application design phase, typically as part of a series of Product Design workshops. Depending on the complexity and scope of the project, functional documentation may include all or some of the following elements:
- Information Architecture – a detailed map of the application’s functionalities, showing all possible user actions within the app and how users will locate and interact with specific features. This element can be omitted in less complex applications with only a few screens.
- User Stories with Acceptance Criteria – a description of the application’s functionalities from the user’s perspective in a simple format (e.g., As a <user>, I want to <change my password> so that <my account is more secure>). Based on user stories, a development backlog and test scenarios are created. User stories with acceptance criteria ensure the development team implements the software’s functionalities exactly as intended. They are also crucial for verifying the proper operation of the developed functionalities.
- UX/UI Mockups – a graphic design of the application that visualizes how each screen of the final software will look. This is one of the essential elements that enable developers to create the visual part of the project. It shows the layout of individual elements on the application screen (UX) and the final appearance (UI).
- Component Library – helps the development team consistently implement interface elements. It is especially important for extensive and complex applications. In smaller projects with only a few screens, it can be omitted.
Who needs functional documentation and why?
- Application Owner: It ensures that the application will be developed according to the initial assumptions, as every planned function is described in the form of user stories and visualized through graphic mockups.
- UX/UI Designers: User Stories documentation enables the design of an interface (UX/UI) that aligns with the users’ needs and the project’s objectives.
- Development Team: It allows the team to understand the requirements and implement functionalities precisely according to the project vision. The component library facilitates the implementation of graphic elements into code.
- Testers: User Stories documentation serves as the foundation for creating test scenarios and verifying the proper functioning of the application during later stages.
Where is this documentation located?
- User Stories: Usually provided as a spreadsheet or PDF.
Information Architecture, UX/UI Mockups, and Component Library: Shared via the design tool Figma, either as a link or an exported file.
2. Technical Documentation
This type of documentation explains the technical aspects of the project, including the technologies used, database structure, frontend-backend connections, and more. It is created during the final stages of the project (if needed). It typically describes:
- System Architecture: For example, monolithic structures, microservices, serverless models, or architectural diagrams.
- Technology Stack: Such as Flutter, React.js, .NET, PostgreSQL.
- Integration Methods: For instance, API endpoints or external systems.
- Database Structure: Details of the database layout.
- Environment Configuration Instructions: Including tools like Docker or CI/CD pipelines.
Who needs technical documentation and why?
- Development Team: To understand how the application was implemented, what technologies were used, and how different components are connected.
This enables quick problem diagnosis, facilitates the implementation of changes, and supports further application development without risking the introduction of new errors.
Technical documentation is especially crucial if the application’s development is taken over by another team or when onboarding a new specialist.
Where is this documentation located?
It is usually provided as a PDF file with descriptions of specific topics and, if necessary, links to external tools (e.g., Swagger API documentation).
3. Testing Documentation
Testing documentation outlines all aspects of the testing process, including planning, execution, and results, ensuring the application works correctly. It typically includes:
- Test Scenarios: e.g., “Can the user log in?”
- Regression Tests: Verifying that new changes haven’t affected existing functionality.
- Test Reports: e.g., a list of identified bugs and their resolutions.
Who Needs Testing Documentation and Why?
- Testers: It helps in planning, conducting, and analyzing tests, as well as reporting their outcomes.
This documentation may also be valuable for:
- Developers: To diagnose and fix bugs.
- Project Managers: To monitor quality and progress.
- Clients: To review test reports and verify application quality.
Where is this documentation located?
Test cases are often created using platforms like TestRail or similar tools that allow for generating reports.
4. User Documentation
User documentation is a straightforward, practical guide for the application’s end users (including those managing the admin panel). Examples of such documentation include:
- Instructions: How to use the application’s features (e.g., “How to change a password?”).
- FAQs: Frequently asked questions.
- Visual Materials: Screenshots or video tutorials.
Who Needs User Documentation and Why?
- End Users: To understand how to operate the application and use its features (e.g., changing a password or completing a report).
- Application Administrators: To receive guidance on managing the application (e.g., adding users or moderating content).
Where is this documentation located?
It is most commonly provided as an online document (e.g., on Notion) or in PDF format.
FAQ – everything you wanted to know about documentation in IT projects but were afraid to ask
- Is creating documentation an additional cost?
Functional and testing documentation are integral parts of the development process, much like programming. Therefore, the time spent on creating them is billed accordingly. For smaller applications, user documentation is usually not essential. If you plan to continue working with the same software development agency, technical documentation might also be optional but can be ordered additionally.It’s advisable to determine the scope of required documentation during the initial offer phase to avoid misunderstandings.
- Which type of documentation is essential?
If you are planning to create a web or mobile application, functional documentation is essential. It defines how the application should work and look. Additionally, testing documentation is a crucial part of the software development process. It helps the testing team plan, execute, and analyze test results, ensuring the application operates as intended. While testing documentation is primarily aimed at testers and quality assurance team members, it can also be valuable for the client, as it demonstrates how the application has been verified for proper functionality.
- Can I request not to create documentation if it’s an additional cost?
If you feel the proposed documentation is too detailed, you can ask to narrow its scope. However, skipping all documentation, especially functional documentation, is not recommended. Lack of functional documentation is like designing a building without a complete architectural plan – you need a detailed specification to successfully complete the project.
- Is a backlog considered documentation?
A backlog is not full-fledged documentation. While it lists tasks and functionalities, it lacks detailed technical descriptions, business processes, or user guides. A backlog is essential for managing work progress but doesn’t replace comprehensive documentation.
- Can I see sample documentation from previous projects?
You can usually request anonymized excerpts or templates from past projects. These maintain confidentiality and comply with non-disclosure agreements.
- What’s the difference between UX/UI mockups and a prototype?
UX/UI mockups are static visualizations of an application’s appearance and layout, while prototypes are interactive models showing how the app will function. Note that clickable prototypes are not fully programmed, functioning applications.
- Will technical documentation be understandable to me?
Technical documentation is designed for developers and other specialists who will maintain and develop the application, so it might not be fully understandable to non-technical readers. This is not a flaw of the documentation.
- Will technical documentation help if I work with a different company in the future?
Yes, detailed technical documentation makes it easier to understand the application and supports its development by a new team.
- Who is responsible for preparing documentation during the project?
The responsibility depends on the type of documentation and falls on analysts, UX/UI designers, developers, or testers.
- How long does it take to prepare functional and technical documentation?
The time required depends on the project’s complexity. For example, functional documentation for a simple mobile app (user stories, UX/UI mockups) can take a few weeks, while technical documentation might take just a few days. More complex projects require more time.
- Will the documentation be available in multiple languages if my app is international?
Yes, documentation can be prepared in multiple languages if needed, but this will incur additional costs.
- Are code comments considered documentation?
Code comments are often used to explain complex operations but do not replace full-fledged functional or technical documentation.
Conclusion
Documentation in IT projects is a collection of materials describing an application’s features, technology, testing processes, and usage. It ensures project clarity, minimizes errors, and supports future development. The scope of documentation depends on the application’s complexity. It’s essential to account for its costs during the planning stage, as well-prepared documentation is crucial for efficient execution and future maintenance.
