This is an opinion piece formed by my 2+ years of working at a software development agency and observing the management of its projects from start to finish. Some of my ideas might be obvious, some questionable or wrong. Please don't hesitate to present any constructive criticism you might find pertinent.
The basic business model for agencies is as follows:
- Find a client
- Make a product they need
- Transfer said product for money
Finding clients is beyond the scope of this article, so I won't talk about it.
To make a product, we need to know what it is.
To successfully transfer it, the client needs to be satisfied.
Enter expectations vs reality
If reality is worse than expectations, satisfaction is negative.
If reality is better than expectations, satisfaction is positive.
Reality - Expectations = Satisfaction
How to quantify expectations?
By compiling a list of the acceptance criteria.
How to do that?
By describing what the app needs to display, how will the users interact with it and what happens when they do.
Identifying the contents
The basic premise of applications is that the user has a problem and the application proposes a solution to this problem. An interface, which the user interacts with, resulting in either a successful or an unsuccessful outcome.
Setup
- Define the problem (users need groceries every week)
- Propose a solution (an app that manages the delivery of groceries)
- Define the features (choosing the groceries and delivery schedule)
User Interface
Define the UI for every part of those features (choosing the test, entering the necessary information, accepting terms & conditions and confirming the purchase, etc.).
The UI is the general design, its components, their styles and organization within the application.
Each UI component must be extracted from the general design of the application and presented in every state, including the animation stops. The styles such as text styles, colors, gradients, spacings, border radiuses and shadows must be listed separately from the general design to be easily accessible and reusable.
Each component and style must be meaningfully named to ease communication and documentation. By extracting and naming each style and component, we are forced to create a cohesive application that looks uniform and is simple to develop. Also, every asset like icons and images have to be appropriately sized and exported.
Functionality
All logic in an application is triggered to execute. Those triggers can be gestures (tap, double tap, long press, swipe, scroll, pinch, pan, etc.), timers, network connections, app lifecycle events and other OS callbacks. We need to define all those triggers across the application. Then we define the desired outcomes for the logic triggered by those triggers.
Application flow
We finally create a graph of all the UI states before, during and after every action on a component, as well as pending states during the execution of the functionality triggered by that action. This graph contains the complete user flow throughout the application lifecycle. Might seem hard to do, but it is really just connecting all the dots we’ve defined in the previous steps.
By now, we should have three documents.
- The design system document (the UI components, their states/variants and styles).
- The functionality document with the defined triggers and logic triggered by them (in written form).
- The application flow document with all the states connected together (in visual or interactive form).
Since we are in the software development business, these documents should of course be linked for the information to be easily accessible between them.
With these three documents, it is now set in stone how the application shall look and respond to interactions and so the expectations have been set. Of course client requirements change all the time, so this composable system also makes it possible to swap out and modify UI elements and functionalities. The amendments however, do need to be documented, so there is no misunderstandings about the acceptance criteria down the line. Going fast and breaking things might be great for prototyping, but not for building final products.
Now to the easy part.
The development
Developing the application after receiving the acceptance criteria is its own story. The codebase needs to reflect the composability of the design and be easily maintainable and extendable.
The codebase is a product in itself, regardless of the functionalities it’s supporting. No matter the product, any developer should be able to understand how the application was designed just by looking at its codebase.
Planning
In the planning phase, we decide on the technologies and tools, state management and data persistence solutions, the architecture of the app and the folder structure, the local (OS) and remote APIs that will be needed. Also, it is logical to work with the tools one knows best, but it might be beneficial to try different technologies on the side, in case some of them prove better than the existing ones.
All the planning decisions need to be documented in a technical specification, to eliminate uncertainty in the future in case there is a temptation to switch tools.
In case the client is responsible for backend development, once the business logic was defined in the acceptance criteria, the client needs to provide accurate documentation for the endpoints needed to interact with their servers. Of course some clients are busy and already have a developed backend (e.g. in case the mobile application will support an existing web app), in which case they should either compile a list of endpoints that can be used for the needed user actions, or they must be notified that figuring out their API will take time.
Development
There needs to be a team lead setting the rules for the project and all the code must be approved by them before being merged. This is someone that knows everything about the technological side of development and can clearly communicate any issues to the project manager. The project manager has to prepare the backlog of issues in conjunction with the team lead, so there’s no questioning the tasks that need to be done and no developer stays without work at any time during the project. I won’t go into project management methodologies, but that’s the gist of it.
I find GitFlow a logical git workflow, so I recommend it be used for most projects. Commits should be concise and contain as few changes as possible while still making sense. Developers mustn’t commit multiple unrelated changes within a file at the same time. Commit messages should be short and to the point, keeping the infinitive verb form (add, fix, merge, replace, etc.).
Components should be developed as a part of the feature they belong to, unless they are used in several features that will be developed simultaneously. That makes them common, and as such, they should be developed before their dependent features, to limit merge conflicts. If a dependent feature is already in development, the other feature should have a stubbed component to be replaced by the developing one. In other words, there shouldn’t be multiple developers writing the same code.
Different developers use different IDEs, configurations and coding styles, so linting rules must be specified that standardise the code format, allowing for easier collaboration, debugging, as well as monitoring changes. Auto formatting a document where only one line was actually changed makes it nearly impossible to find the change if the whole page looks different. SOLID & Clean Code principles should be followed as much as possible.
Since we’ve clearly separated the UI from the business logic in the “Identifying the contents” section of this document, they can be developed separately.
All the existing styles need to be defined before doing any UI work, to minimize any merge conflicts if different developers edit the styles at the same time. Of course it is impossible to eliminate conflicts altogether, but we should aim for as few as possible. Flutter provides a framework for defining themes, which is worth looking into to limit files with constants and increase dynamic styling in case it is needed.
Once the technologies and APIs have been defined, there need to be wrappers written to abstract out the implementations of the APIs so they can be easily replaced later.
These are all the miscellaneous rules I think need to be specified for development. Now the only thing left is to clear out the backlog of issues.
Testing
Testing is of course a big part of building anything, unless it’s my castle in Minecraft. Don’t touch that. An agency should have at least one QA engineer that is experienced in testing applications both manually and automatically. As far as I know, they are the ones writing integration tests and making sure the application works as intended, not the project managers. They are also the ones rejecting the code in pull requests. Also they know how to investigate issues and write bug reports so the developers don’t waste time trying to figure out if there is actually a bug or someone just fat-fingered a button. Of course, developers don’t get out scot free. I believe it is the developers’ job to write unit & UI tests and making sure their own code works.
Release
In the agile world, something like a bi-weekly release is a reasonable thing to do in my opinion, since it might take a couple days to incorporate the code built by different developers, thus leaving a whole week for development.
Final Words
This document was long, but I’ve tried to keep it as concise as possible, barring a couple jokes in the last few sentences. Software development is a complicated business and agencies don’t need to complicate it even more by working without structure.
If this whole process is done correctly, the reality will likely be even better than the expectations defined in the acceptance criteria, and the company will gain (or keep) one more satisfied customer.
I am aware, that for some companies, this approach will introduce some short-term costs. It takes time to adopt a new process, to learn and become efficient with seemingly unimportant, but time consuming tasks. However, I believe once such process becomes second nature, it will greatly increase the productivity and profitability of making and transferring products to clients in exchange for money.
Top comments (0)