Blog article
See all stories »

How Documentation can Save Your FinTech Project

FinTech is a high risk high reward industry. Most think about the “reward” side of the equation, but the real experts understand the value of risk mitigation.

A common risk of software development is making compromises that will back the team into a corner with things like bugs or technical debt. These issues can be covered with basic development fundamentals — thorough testing, extensive quality assurance, and a diligent attitude towards refactoring. But there is one more fundamental prerequisite to a projects long-term success — documentation. This includes support documentation, testing documentation, and the general documentation of processes surrounding the development, maintenance, and functionality of the project.

Your team’s approach to documentation will determine how much of a headache your software is going to be in five years. Here’s what our team has learned about documentation in the past 19+ years.

The Value of Documenting Everything

With complex FinTech projects, before you make a change to any functionality, you need to fully understand why it’s there.

Think of the Chesterton’s Fence dilema: Do not remove a fence until you know why it was put up in the first place. Your original development team might be long gone, but if their work is well documented, you will know exactly why each line of code is where it is. If you write it down once — you never have to think about it again. If there’s a debate for how things should be done, or a request to change a process — you can refer to your documentation to explain it or remember why you came to the conclusion you’ve come to.

Creating consistent documentation is also a great way to get out of “tunnel vision”. When your team has to explain their decisions, they will be more likely to notice flaws in their decision making process. Documentation is a double-edged sword — you’re not only helping somebody in the future, you’re also making sure your current decisions are rock solid.

Documentation is a prerequisite of Growth

To leap off the previous point — all new developments are built on the foundation of what’s come before. Very few companies have the time or the budgets to “reinvent the wheel”, so no matter what anyone tells you, nobody is building your product or service from scratch.
There are a million jokes on Twitter that the difference between a good developer and a bad developer is how quickly they gravitate towards Stack Overflow to find answers to their questions, and there is a grain of truth for that. While Stack Overflow might swoop in and save a developer in a pinch, what really helps them solve problems is thorough documentation of the project they’re working on. If all projects in a company are thoroughly documented, then when the time comes to add a significant new feature or start on an overhaul of an outdated solution — the foundation for all of this is already there. Instead of spending weeks (sometimes months) on expiration, your team will be able to refer to the documentation and start building on what’s already there with a full understanding of everything that’s going on behind the scenes in the software code.

Documentation is a Cost Cutter

As an outsourcing company, we’ve encountered hundreds of projects. Inevitably, there is some overlap between them, and we find ourselves doing similar things for different clients. Based on all this, please let me present you with some real numbers.

The average bill for adding a new feature to a well-documented project is, on average, 30% lower. Here is a breakdown of why:

  • Documentation eliminates the need for “exploration” of the code base
  • Clients with understand their own project’s needs, and are able to define requirements clearly, eliminating the entire “discovery” phase of working with a new team
  • Because documentation already exists, the new team simply contributes to it, rather than creating it from scratch
  • Understanding legacy code significantly reduces the number of regression defects

This might not seem like much, but even a 10% cut on a development bill can be the difference between a company being able to meet consumer demands or having to get by with a less-than-ideal software suite helping them run their business.

Practical Documentation Tips

Now that the business value of good documentation has been established, let’s move on to practical tips to ensure your software’s long-term success.

1. Documentation is an Unskippable Step
Documentation is a key step in most IT processes already. A good team will use a project management tool where they will break down objectives into clearly defined tasks, developers will move their assignments across a Kanban board, and QA engineers will create bug reports for the development team to work on. Even the most die-hard “startup culture” adepts who want to “move fast and break things” still understand the value of some organisation within their development process.Slowly but surely, further documentation is slowly transforming from a best practices recommendation to an actual step that many teams are taking seriously.

Still, too many teams treat documentation as an extra step to come back to after development is done, instead of including it as an inherent part of the process. It’s time consuming, it requires a perspective shift, and (so far) very few have been able to include documentation as part of their development flow.

2. Document Key Functionality
If you are working with an in-house team, make sure that they are documenting their decisions. This will ensure that if you ever find yourself with an entirely new team, they will know how to continue from where the previous team left off.

This tip comes from two cases when a client reached out to us because their new team could not keep up with the growing demands of their software’s users. Over time, individual developers left the team and got replaced, until one day (like the Ship of Theseus), the company found itself with a team where nobody had a full understanding of the project. They chose to outsource future development of their software to a team that took documentation seriously and would not put the business in the same situation again.

3. Document Processes
The same goes for processes. Even a rough sketch of a change in your onboarding process (for example) is easier to note as you’re making it, rather than months later, when you take the improvement for granted and might no longer notice it’s there. As a rule of thumb: if you think something isn’t important enough to document — you’re wrong.

Our team documents everything — from the process of scouting, hiring, and onboarding new employees to the simple processes of Git pushes and pulls. These are things a developer does multiple times a day, but having an established process ensures that any newcomers will be able to fit right into an existing team dynamic.

4. Document Everything
And I mean everything. It’s better to have too much documentation than not enough. When you have reached the when there is documentation on how to create new documentation (and your team follows the process) — then you can rest assured that five, ten, or even twenty years down the line your decisions won’t back you into a corner.

5. Include “Documentation” as a step in the development flow
Any extra step in the development process has a cost. With documentation this cost can be paid with time or with money. To pay for documentation with time, include the documentation process as an acceptance criteria for every task. This means that before a team member can truly mark a task as done, they have to document their thinking, explain their reasoning, and provide documentation for the feature they have created. This will take them out of the development “flow”, wherein they can tackle one task after another as they’re “on a roll”.

If we look at the research behind this, switching from one task to another requires at least 25 minutes. This means that with every completed switch from coding to documenting, your developers will lose approximately 1 working hour. With the complexity FinTech projects tend to have, this cost adds up.

To tackle the documentation requirements with money — simply hire someone to work on the documentation in parallel with your development and QA engineers. This can be a business analyst, a project manager, a delivery manager, or anyone else on the team who is expected to have a holistic understanding of how the product they’re developing is supposed to work. For these people, communication and language is a core component of their daily working lives.
For 90% of cases, I would recommend dishing out the money.

6. Check for Documentation in Outsourcing Partnerships
If you’re outsourcing, it’s important that your vendor is responsible about documentation. There are a few ways to check if they are. After all, the old adage of “how you do one thing is how you do everything” applies to development. If you’re a FinTech company looking to outsource the development of your product, you can look at a company’s documentation of their processes to assess how well they will document the development of your project.

As the CEO of a software development outsourcing company, I know this first hand. We’ve lost several prominent leads because we did not have proof of our development process maturity. So, it was important for us to be CMMI appraised to prove our maturity level, and it was important for us to get an ISO certification to prove to potential clients that their information and intellectual property would be safe with us.

CMMI appraisals and ISO certifications are clear signals that a company is mature, that their processes are documented, that the security of your intellectual property is solid.

Furthermore, ensuring that your outsourcing vendor provides thorough documentation will prevent vendor lock. Just how documentation can help your in-house team during personnel changes, your vendor’s documentation (if done right), will allow you to easily choose to work with a different partner in the future. If, all of a sudden, you become unhappy with the services of your developers, changing to a new team will not completely destroy the well oiled machine of your FinTech project development.

Conclusion: Documentation is Part of the FinTech Culture

The reason documentation is important in FinTech is that it’s simply part of the culture. From securing VC investments to having extensive support documentation for B2C products, FinTech is the only industry (other than Healthcare) where it is nearly impossible to get by without thoroughly documented processes and clear project documentation.

So, when a FinTech business looks for outsourcing vendors — every little sign of “this team knows how to document things” is important. From a CMMI appraisal to an ISO certificate, and even to the way a company presents their RFP — every little signifier of an organised team is a big plus.


Comments: (0)

Max Zorian

Max Zorian

Founder at QArea and TestFort software development

Qarea and Tesfort

Member since

22 Jan 2021



Blog posts


More from Max

This post is from a series of posts in the group:


Fintech discussions and conversations around the development of fintech.

See all

Now hiring