Your software developers should be delivering more than code

When a client commissions bespoke development, there’s a common assumption that the source code is all that matters when it comes to what a client owns. However, that’s only the tip of the iceberg and you, as a client, should make sure you’re up to speed on the other essential artefacts of software development and ensure they’re within your control.

Your application is more than source-code

It’s true that the source code is an essential element — without that, you’re sunk. However, there’s more to source code than the code itself. I can guarantee that there are other dependencies required to run the system. For example, third-party libraries that provide functions such as PDF reports or graphical charts.

That leads on nicely to the next set of artefacts that you should have, documentation. This comes in a variety of forms, and I could write reams on this topic alone. At the least, there should be documentation describing how to get the system running. It needs to include references to those dependencies and the specific versions required. Make sure it covers any external services needed along with all the credentials and licence codes that are necessary to access them.

What does it even do?

If your application is to remain maintainable, then there should be documentation that covers what it does and how it works. It can often be user-facing and doesn’t need to be lengthy prose. It can be video or annotated screenshots. I can’t count the number of times we have had clients forget that the system already provides the functionality for which they’re asking.

In the course of supporting your system it’s likely your developers have created scripts and procedures to make rote tasks repeatable and consistent. If you pay developers to provide support then, to our way of thinking, these scripts and procedures belong to you. If you choose to move on to another developer, then they don’t need to reinvent the wheel or rediscover essential maintenance tasks.

Next, are the artefacts that are generated during the course of a project. These are quite wide-ranging but can include sketches, mockups, design documentation, technical architecture documents and decisions made.

Shared Knowledge

They all contribute to the development of the codebase and are all part of the shared knowledge created as the application develops. When new contributors join the team (both client and developer), they can use these to get a head-start. They don’t need to take up others time to gain an understanding of the system; time that is better spent on progressing the project meaningfully. It also helps everyone remember and understand the context and trade-offs of why particular decisions were made.

Far too many developers disdain documentation, but it’s vital. Don’t get me wrong, I’m not an advocate of lengthy documentation for the sake of it, but strive to strike a balance between usefulness and utility. Documentation is pointless if it doesn’t have a clear purpose or get used. Moreover, if it becomes a chore, then it will get outdated which is worse than useless.
More often than not when budgets are tight, documentation is first to get skipped because it’s deemed “non-essential”. However, when problems occur, or broad changes need to be made, then documentation is a huge timesaver. The time spent creating it during the development of a feature is far smaller than the cost later required for developers to reacquaint themselves with the details of the codebase.

Take control

Any long-term development project should have documentation, and it is part of the cost of development to ensure that the value in the software is maintained.

It is critical that you be in control and have access to all this documentation. If you don’t know, then have a frank discussion with your developers and make sure it’s written into your contracts. If you need any help or have any questions, I’d be happy to help. Schedule a free 15-minute call with me if you’d like some impartial advice.