After spending thousands of dollars and months of time working with a software development agency to build your app, what are you, the client, actually “getting?”

An app, of course, but what goes into an app? If you were to pass your project off to another team or take over internally, what would your tech team need to get up to speed?

If you have no idea what to expect in-hand at the end of an engagement or if all you have to show for months of work on a project is a .zip file of code, this article for you.

A .zip File of Code isn’t Good Enough

This article was written as a reaction to something we’re seeing from a lot of clients who come to us after working with another agency:

👉🏽👉🏽👉🏽 Founders only bringing us .zip files of code.

Though common, we find this to be pretty bad practice, and it makes your new dev agency or in-house team have to work a lot harder to figure out what’s going on.

Why a .zip File of Code is a Problem

Imagine you’re new in town and just learning how to drive. Then someone gives you a brand new car!

Except, they didn’t bother to include the user manual or a GPS.

So while you may have a perfectly functioning car, you don’t know how to turn it on or get it in gear or what all those buttons mean or how to get where you want to go.

It’d be really hard to use your new car to the best of its ability, right?

Just like driving ≠ having a car, building a successful product ≠ having code.

There is a lot more at play than just writing code when you build an app, so there is a lot more of context you should be receiving from your development team. This will also ensure the context for your product is owned by you and your company, not your outsource development team.

5 Things You Should Ask Your Dev Team For Up Front

Yes, we want an app, but there are many things that go into understanding that application, how it’s set up, how data moves, etc. In order to get a holistic view of your technology, there are 5 deliverables that are important to understand. Have a conversation about receiving these things from your tech team before work begins (put if in the contract, if that’s helpful), and then make sure you actually get them when things wrap up.

These 5 things don’t just deliver a working app, they will ensure you have the context any developer would need to begin working on your app, the reigns to take over the work, and the framework for understanding how your application works. Those 5 things are:

An architecture document
A password vault
A git repo
Documentation
Design files

Here’s how each will set you up for success, no matter who works on your app next:

Architecture Document

Architecture documentation for an app is a description of the software's design and structure. It outlines how the various components of the application interact and work together to meet its functional requirements.

Architecture documentation is vital for ensuring that everyone involved in a project—from developers to stakeholders—understands the system's design and can make informed decisions. It's also crucial for maintaining the system over its lifespan, facilitating updates, troubleshooting, and adding new features.

An architecture diagram is a helpful tool within your arch documentation, as it visualizes the way data flows through your product and typically looks a little something like this:

This architecture diagram shows the standard architecture for a ready-to-scale web application.

Password Vault

Your application will be built using any number of third-party tools (like Twilio for sending texts or Google Analytics for app analytics). Each of those tools will require a user account, so each external tool will have a unique login credentials.

Request a password vault that contains any login information you would need to access the third-party accounts used in your application. A password vault, or password manager, is a secure tool that stores and manages various passwords and credentials. This tool is especially useful for maintaining security and organization when managing numerous accounts or handing over information between parties.

We use 1Password at ThinkNimble.

One thing to consider when it comes to third-party login credentials - sometimes developers create accounts under their personal email or Google account. At the start of the contract, have an understanding of how user accounts will be created - do you use hello@yourcompany.com? Can they add you as an additional user? You don’t want your third-party apps owned by your outsource developer, so make sure these accounts are owned in-house when they’re being created.

Often no one notices this issue until months or years later when something breaks, access it turned off, or some other misfortune. By then, you might have trouble reaching that old dev who built it. And even if you can, there is a good chance they have no idea what the account is or how to access it…because it was a long time ago and it wasn’t written down. WRITE IT DOWN…IN A PASSWORD VAULT….USING CREDS THE CLIENT OWNS. 😇
- Ed Romano, Tech Lead, Senior Software Engineer

Your Git Repo Transferred to You

A Git repository, often referred to as a "repo," is a storage space where your code and project files are stored along with their revision history.

Git is a version control system that tracks changes to files and helps multiple people collaborate on the same project by merging updates and maintaining a history of who made which changes and when (similar to how Google Docs tracks revision history).

A repository can be hosted on platforms like GitHub, GitLab, or Bitbucket, allowing developers to push their local changes to a remote server where team members can pull the latest updates, review code, and contribute to the project. This system is crucial for managing larger projects or projects involving multiple collaborators.

Before the projects starts, ask your dev what they plan to use. The answer here should almost always be a git repo (GitHub, GitLab, etc). If they don’t say a git repo, that’s a red flag.

We’ve had companies come to us saying their old developers can’t transfer the repo to them. This simply isn’t true. Every Git repo has the ability to transfer repo ownership. And you should own your repo.

Documentation

The purpose of documentation is to make it easier for future engineers to understand how things work.

Documentation within an app refers to the set of materials and guides that explain how the application works and how to use it. This is crucial for new developers onboarding to a project and to avoid all the information about your application living in one developer’s head.

Documentation is most often done within your git repo (one more point for why to have your repo transferred to you). Engineers can leave notes throughout to explain how things work, how to get the code running on another engineer’s local environment, good things to know, etc.

This particular documentation explains why a certain change was made and how to test it. This context is immensely helpful for knowledge share across your dev team.

Documentation helps to ensure the software is accessible, usable by new engineers you onboard, and maintainable. There are lots of ways documentation is beneficial throughout the entire product process:

API Documentation: Information about the APIs provided by the app - how to use them, parameters, and examples of requests and responses.
Code Documentation: Comments and descriptions within the source code itself, which explain what the code does and why certain decisions were made.
Architecture Diagrams: Visual representations of the software architecture, showing how different parts of the application interact with each other.
Development Best Practices: Standards and conventions to follow during the development of the app.
Build and Deployment Processes: Step-by-step guides on how to build the application from source code, run it locally, and deploy it to production environments.
Testing Protocols: Descriptions of how to conduct tests on the application to ensure functionality and performance.

Effective documentation is an essential part of any software project, particularly in complex applications or when teams are distributed.

Design Files

Design files are the easiest way to prototype new features and communicate visual expectations for your product, and owning your design files is vital for iterating on the first version of your application.

Your design file will likely be housed in a tool like Figma, Sketch, or Adobe XD. These files contain layouts, interactive elements, and visual designs, which are used to prototype, test, and finalize how an application will look and function. They serve as critical references for developers implementing the design into functional software, ensuring consistency and alignment with the envisioned user experience.

Owning the design files for your application gives you the resources needed to onboard other designers (or make your own small changes if you know the software) and frees you from being dependent on the original designers or facing additional costs for accessing these files.

This autonomy also facilitates faster decision-making and implementation, crucial in responding to market feedback or changes, and ultimately empowers you to maintain the integrity of your vision and brand as your application evolves.

In Conclusion

As you work with different stakeholders throughout the development of your application, remember that you’re not just paying them for code.

You’re paying them for a full package of technical assets that you would expect from your own in-house team. Owning these assets means owning your business logic and the ability to manage your technical team on your terms.

5 things (that aren’t code) you should be getting from your tech team