What project documentation should my software partner deliver? Good practices guide

I am agile. Why do I need documentation in my flexible approach? 

“Working software over comprehensive documentation” is a practice often quoted in Agile management rule books. One might agree, but from the other side what keeps software projects from failing if not good communication, mutual understanding between the parties and flawless teamwork? Documentation helps in gathering all this in place. In Agile projects, reducing documentation to a minimum doesn’t mean resigning from it totally. Agile is about curtailing the planning stage, but still includes general goals and roadmap of the project.

The documentation in the Agile project will serve the purpose of keeping the changes aligned with a general plan and core requirements even with full flexibility throughout the entire project. Of course, it doesn’t have to mean exhaustive description of each feature in the planning phase but rather keeping team members and the software stakeholders headed in the same direction towards the project objectives. 

One could argue that a well-managed team with experience in working together will not need to follow written rules and verbally passed information will be enough to maintain a good development compliant with the requirements. That might be the case in some projects, although if you look at the standards in professional software teams, you will see their processes include gathering the proper documentation not only in the case of business requirements but also on the level of coding, testing, architecture setup etc.

If you pass the knowledge to the team through written documents, you can be sure that the instructions will be clear and there will be no doubt on what has been said. The same thing between the stakeholders, Product Owner and the Project Manager. When you present your project to your supervisors or the investors or auditors, the documentation will dispel all the doubts they might have about the requirements, implementation or the outcomes.

How to gather the documentation? 

While types of documentation differ from project to project, the approach common for all of them is that the documentation should be created in an organized way and just enough for the purpose it serves. Once you start planning the documentation approach, ask yourself who your audience is and what they need to know. Are they your team members, customers or other developers? Maybe the committee of particular authorities who will be assessing your project?

Adjust the message to the receiver. Make it easy to read, usable and helpful. Remember - your audience is not you, do not assume they know something, make it clear for everybody who has never touched the topic before.

Avoid creating it too complex, because it causes inefficiencies. Compose the message that will be comprehensive enough to cover all the doubts. Try to find a middle ground between no documentation and too much documentation. Poor documentation will force the stakeholders and team members to assume things that are not covered. At the same time, an abundance of documentation, repetitions, and the text overwhelming the essence will make people spend too much time on reaching to necessary data. There is also a high probability they will get frustrated with difficulty to find what they need. 

To facilitate your work, improve the process of gathering documentation and make it more effective. Before the project starts, plan what type of documentation will be needed in a particular case. Assign documents creation to the team members and place them in time. Systematic documentation updates ensure all the changes are tracked and fresh information is codified when the people remember them the best.

What documentation do we create in Merixstudio? 

Here in Merixstudio, we follow the “fit-for-purpose” documentation rule. The small MVPs will require less documentation than big corporate projects or products under rigid legislative constraints. Below you will find different kinds of documentation from different projects collected into groups. 

1. Business requirements - functional and design documentation
2. Project Management and implementation process documentation
3. Testing documentation and verification protocols
4. Code and data architecture documentation
5. User documentation

1. Business requirements - functional and design documentation 

This documentation is gathered mainly on the planning and design stage, although in Agile projects it happens throughout the whole development process. It lets engineers, designers and stakeholders mutually understand the business goals, the underlying technology and agree on the acceptance criteria before the project starts. It ensures effective translation of business requirements into design, technical specifications and development plan. The more waterfall-oriented development methodology is, the more thoughtful planning and the more detailed content is created on this stage. 

In agile, the documentation performs more as a direction indicator and contains only essential information to keep going forward while Waterfall teams carefully create detailed documentation before the development phase. The goal of this precise planning is to make them sure that no changes in the project arise, but of course, in many cases, it’s impossible to predict the progress of the project at the very beginning.
 
a) Project charter - basic information about the project that let the team see the bigger picture. You can include here business goals, objectives and constraints, business model and business rules, background and strategic fit, solution directions, identities of the stakeholders, pains and gains from the project, competitors, geographical markets, regulatory constraints, risks identified early on, high-level budget and spending authority. Often the first stages of the project are backed with research records which let to build the project on a good knowledge background. 
 
b) User personas, user stories and story mapping - characteristics of users, their behaviour, thought patterns, and motivation are converted into the business logic, user stories, use cases, roles and responsibilities of each actor in the app. The steps that a user persona takes to accomplish a specific task are merged into a User story map. (see the example below). 

c) Mockups/UX architecture - depending on the project specifics, different design assets are being created: wireframe diagrams and mockups, user interface sketches, site maps, prototypes, user flow schemes, functional architecture and design principles. The most important tools used at this stage are usually Sketch and inVision. 

The user stories are being transferred directly to Confluence software and converted into the backlog in Jira software. Jira backlog consists of user Jamstackstories. The user stories are carefully analyzed throughout the project regarding possible tech implementation. Each user story has its tech assumptions and is already planned on how it will be implemented and the acceptance criteria are set. In Jira tasks, the Project Managers set precise descriptions (understandable for engineers) of how well-executed task should look like (Definition of Done and Definition of Ready). The functional documentation will often be complemented with technical planning and in-scope and out-of-scope items to build the estimation document which is a starting point to talk about the budget with the stakeholders.

Create story mapping, sketches, user personas and many more during Product Design Workshops. 

2. Project Management and implementation process documentation 

Here, Project Managers describe the activities surrounding the process to provide organized and well-planned development. They make sure that the team and the stakeholders are on the same page and that the development process follows the requirements.
 
a) The tasks within the project are set in time and organized into a development roadmap and release plan. It is sometimes visualized in the form of a Gantt chart with dependencies between tasks, although only certain types of projects need it, it is not necessary in many cases. A release plan set in time allows keeping the project organized, on-budget and on-time. 

b) The backlog set in time is organized in the Jira tool in the Kanban board that prioritizes work within each sprint. Kanban board in Jira consists of following columns: 

• to do, 
• in progress, 
• ready for code review, 
• ready for QA, 
• in QA, 
• done. 

The progress in each of the tasks (task are linked to business scope and the code) is tracked. Jira software notes the time of each task passing through the columns, testing, bugs that appeared and the time of fixing them. This way the full rack and transparency is kept throughout the project.

c) Process assumptions, tools and procedures - those provide clarity over how the software will be implemented. They describe the team composition and their responsibility, kinds of meetings throughout the project, ways of communication, risk management procedures, change implementation and software release procedures.

d) Documents gathered while the project is going: kick-off document, sprint goals, sprint review and planning notes change control (what changes appeared throughout the project compared to the initial scope and assumptions), risk control document and when the project is finished - handover document.

e) Reports and metrics - Project Managers keep track on productivity through velocity chats, sprint burndown charts, and release burndown charts generated via the Jira tool. Reports let the Project Managers see how much time and human resources were spent on the development and what actions influenced the team’s productivity.

3. Testing documentation and verification protocols 

Testing documentation is often needed when the application owners have to fulfil regulations requirements or pass due diligence process for certification purposes. It lets them make sure that the software is aligned with the requirements - the planned shape of the software described in initial requirements is properly implemented.
 
a) BDD test scenarios - composed out of test cases (based on Jira backlog) that outline the actions that should happen in a particular feature, their expected outcome and the effect of the test. You can see the exemplary result of BDD testing in the picture below. BDD scenarios are also a kind of test plans, procedures of how the code will be tested.  

Source: Github

b) Reports from manual functional black-box tests, reports from automated functional UI tests and functional API tests. 

4. Code and data architecture documentation 

This part of the documentation is mostly prepared to facilitate further development of the app and the possibility of using the API by other developers. If the code is not documented, understanding the development process can be time-consuming for some developers. With proper documentation and keeping the good coding guidelines, a product is a long-term asset ready for acquisition and further development

Lack of documentation is one of the signs our codebase needs refactoring. Check what are the other ones. 

a) Developer statement, software development approach, API contracts - information about how the code is built, what development rules, guidelines and policies are implemented in the code, code style approaches, software development procedures, what tech constraints does the chosen technology impose, how the technical issues are solved, environments, reasoning behind application architecture. They are accepted by all developers before the start of the project. 

b) Software architecture documentation - it shows the architecture of the data flow, code dependencies diagrams and server architecture. 

c) API documentation and API integrations architecture (endpoints, authorization, instructions on how to do code integrations, how to effectively use and connect to the required APIs).

d) “Readme” added to the code stored in GitLab, GitHub or Bitbucket repository - even when the code is well-structured, it needs an explanation. Providing “readme” and further description is not only a good practice but necessary documentation in professional software teams. The readme contains the instruction on how to run the product but often also code and functions descriptions. It is the document that outlines the reasoning behind choosing proper libraries, coding practices, particular solution choices that may be potentially confusing for the other developer.

5. User documentation

User documentation explains to the users how their problems will be solved by using the app. It helps them to learn how to use the software, especially the complex one. It covers user manuals, tutorials, user guides, installation guidelines, FAQs, support portals.

Take time to prepare documentation and... save time

Gathering software documentation is a time-consuming practice in the short term but later it saves hours on the meetings and helps people to get to the knowledge whenever they want and understand clearly what the author wanted to say. That is why in the long term it reduces wasteful overhead. The documentation lets the software teams minimize the bus-factor so the software can live their life and be independent on the people who created it and can be taken over by anyone. It is a value-driven approach in the dynamic agile world where things are changing from sprint to sprint. With good coding practices and good documentation, you can be sure that your product will be scalable and easy to understand, use and further develop with no time waste. And no time waste means happy stakeholders.

We do know the importance of properly prepared and meticulously gathered documentation and we’re eager to help you with it in every stage of design and development. Check out how we can help you with your project.