Business Risks of Software Documentation | We Are Capicua

Poorly made software documentation can become an expensive headache down the road. Often, the trouble begins when a venture decides to switch an already developed software product to another development team.

Worst case scenario, Team A provides a .rar file and a “good luck!“. This practice leaves Team B struggling to figure out what to do, or even if they accept the project. As unprofessional as the latter scene may seem, it happens with a hard-to-believe frequency. Blame usually gets at developers, as they have some reputation for not being fans of taking time to document processes. Yet, decision makers are ultimate responsibles. If a project leadership doesn’t make documentation a priority, it won’t get done.

Is software documentation the last thing to consider?

Without a background in software development, it’s easy to think about documentation in a simple way. Kind of like an instruction manual, given at the end of a project: helpful, but not essential. Those who don’t have technical experience, might have to outsource 100% of the project’s development. In these cases, software documentation may never even enter the conversation. If the development team agrees to low, fixed-price budgets, documentation becomes extra work they simply can’t afford to do.

If a team advocates for documentation, the owner is not always convinced. They usually see this task as extra time, or as attempts of selling them unnecessary stuff to get more money. As a result, teams simply make the product, and receive a pay. But, on the other hand, owners have no idea of what they’re acquiring. We know the challenges a founder has to face to get their product on the market. Keeping this in mind, it’s hard to say to them “Hey, you got to learn about this other thing, too”. However, knowing a few basics can help you to keep the project away from potential dangers.

Software documentation is more exciting than it looks!

Software documentation is not just a user manual given at a project’s end. It’s a dynamic process happening in every single stage of development: planning, development, and release. Documentation is, rather, a complete record that shows how developers make a product. It shows the product’s history, explains choices and chances, and gives instructions to both developers and users.

Basically, it's the history of a project + explanations about how the product works.

Planning

Definition of requirements, high-level design and visual contract

At the planning stage, you can think of documentation as a list of requirements and wireframes. In most projects, this will turn into a high-level design. This stage defines both the architecture of the project and the “how” of its features.

Additionally, we like to invest time in making a clickable mockup. After evaluating features, we translate them to design-terms, with Sketch and Invision. After that, the client can determine if the project functions as intended, or how features look and work.

This prototype becomes a visual contract with clients, so we’re on the same page, and features are correctly budgeted. Besides, it acts as the product’s blueprint, so developers have a precise guide to follow.

Development

Documentation within project management software

On the development stage, project management software helps to semi-automate the documentation process. For example, our team uses a combination of Confluence, Jira and Git. These programs integrate with one another, making them even easier to use. The best part is that documentation gets created in lockstep with optimal management.

CONFLUENCE: Acts as a global collaboration tool, like a reference book for a project. It contains the product’s roadmap, requirements, meeting notes, team decisions, and technical documentation.

JIRA: This is the task-maker: teams create a product backlog, at the beginning of a project. These tasks can be directly pulled from features descriptions written in Confluence. The tasks contain workflows, in order to organize the process, and assign roles inside the team. As the project avances, it’s easy to reorganize, reassign, or edit tasks as needed.

GITHUB: Git allows teams to store and update code in a way that shows its history, like a code’s guardian. Team members upload code to Git in “commits”, with explicative notes. With this tool, developers can see when each batch of code was stored or uploaded, and who did it. They can also read the developer’s notes. Developers or teams can create multiple backups in the code. This allows them to go back to an older version in case something goes down.

Release

End-of-project deliverables

Once the team finishes the project, there are several types of documentation that its owner must receive. We think of them as a checklist of the next items:

A. CODE: Code itself is, obviously, the main priority. But, there are good and bad ways to deliver it. When a team is done with a project, they’ll fork the code base. This allows the next team to see the product’s whole history in the repository. Otherwise, the new team can’t see it, and the code becomes just a file without context. The codes come with explanations, known as code comments. These short texts are for human eyes only, explaining the code’s method. Ideally, they should be helpful and well written.

// I’m not sure what I was doing here. Have fun!

There’s a well-known joke among developers, about “good code documents itself”. But, in reality, experienced developers know that it’s possible to forget important details, even on most elegant solutions.

B. RECORDS: It’s important to offer records of Confluence’s work. You can export them into PDF or other document formats.

C. USER DOCUMENTATION: Some projects may require instructions for users, though not all of them. This is an optional item.

Solid Documentation’s Benefits

Good Documentation:

Facilitates communication between team members, project managers and stakeholders.
Tracks important changes and decisions.
Cuts down on emails and meetings, as everyone can check the project status through the software.
Makes it possible to easily add developers to a project, since they can be brought up to speed quickly.
Encourages better coding practices.
Leads to a faster bug resolution.
Shows who did what, creating a point person if questions or problems arise.
Enables easier transitions from one team to another.

How to know if a team is properly documenting

At Capicua, we always recommend hiring team members with great reviews and references. It doesn’t hurt to ask for contact numbers of past clients, to speak with them personally. If you’re hiring a developer, ask them about their documentation processes. What programs do they use? How do they organize their work? Ask them if they allow clients to access tracking tools, and what they promise to deliver after finishing the project.

A huge red flag rises if a team skips or rushes through the planning stage. Another warning sign appears if they come back with a quote well below market’s rate. We know it can be enticing to choose the cheapest and quickest option. But the reality is that, when cutting corners, documentation is the first thing owners leave aside.

Conclusion

Documentation is not an extra. Rather, it’s an important part of a properly managed software project. While developers have their own reputation, it’s ultimately a decision maker's responsibility to include documentation in the process.

This may require a small investment of time and money, yes. But pays back by creating higher-quality products, and facilitating efficient development. You can also check our article about onboarding tools and softwares for more info!

Where to start on App Design?