In today’s agile tech world, we want everything fast. We want faster design, faster development, faster testing and faster deployment. But counterintuitively, sometimes the pursuit of going faster can make us go slower. Moving over from the waterfall methodology over to agile certainly brought several advantages to the way we work today, like:
- Increased focus on the customer throughout the development process through regular communication and engagement with the development team, so expectations are well-managed on both sides.
- Greater flexibility to adapt to the customer’s and the market’s ever-changing demands.
- Tight integration of the testing process with the development process, which helps in finding and resolving breaking bugs sooner, rather than as a “big-bang” at the end of a waterfall-based project.
While I wholeheartedly agree with the above virtues of agile, especially in the case of startups, which are continually changing, I do believe that there is value in looking over and smartly incorporating one aspect of Waterfall in particular – technical documentation.
Documentation – Agile vs Waterfall
Waterfall projects put great emphasis on technical documentation (like use-case diagrams, sequence diagrams, class diagrams, etc.) and having these artifacts ready before development can be very helpful to the development team when they are faced with tough technical problems, which cannot be solved by just “pushing through”.
While waterfall teams do reap the rewards of comprehensive documentation, a common drawback of this approach is that it lengthens the feedback cycle, be it from testing internally, or feedback coming from the customers and users of the product. Shortening the feedback cycle has the key advantage in taking technical and business decisions based on reliable, real-world data instead of making and documenting random guesses and hoping for the best. After all, there is no point in spending time and money in building a product that no one wants or needs.
This is one of the first things Agile addressed. One of the core principles of agile mentioned in the Agile Manifesto states agile will focus on, “Working software over comprehensive documentation”, and while I agree that too much documentation can significantly slow down a team, the right amount can have substantial benefits to the overall effectiveness of a development team.
How do I know this?
During my early days at SeaLadder, when I had just started to gain some confidence at work by removing simple bugs assigned to me by my team lead Adam Pond, I hit a major roadblock. I was now tasked with populating SeaLadder’s database with seed data to generate customised recommendations for users, which could only be accomplished by fully understanding and navigating through the complex web of classes and interfaces on which our product was based. So just like any developer would, I went straight to look at what our product’s class diagram looked like, but there wasn’t too much to see. It looked something like this:
Not very helpful? I’m sure you would agree, so I asked Adam why it wasn’t complete even though we were so far into the development process. He said that the team never felt the need for one up until that point and the tradeoff of spending time to design one instead of developing more features for the product was just not worth it for such an early-stage startup.
After a brief discussion (and some convincing on my part), we decided that I would make a quick and functional class diagram outlining all the classes, interfaces and their respective attributes, functions and attributes which would get us going in the face of similar problems, without slowing us down too much. I was convinced that it would be worth the effort and would help all the other developers in my team as well as me in a similar position.
So I got to work on our class diagram. Having just learnt about Test-Driven Development (TDD) at the time, I decided to use the same mindset while building our ”agile” class diagram, which I can sum up with the following question:
What is the least amount of work I need to do to make this functional?
It turned out to work out surprisingly well! I was able to get a decent class diagram ready within one hour (which was less than the time I had already spent scratching my head on my last task) which helped me to solve the problem I was tasked with. Throughout the rest of my internship, my team and I have repeatedly referred to the class diagram to solve new problems. When they found it to be lacking, the team built upon on my progress and corrected my mistakes, improving its quality iteration-by-iteration until it became the go-to resource for us to get over our technical hurdles. If this doesn’t capture the very heart of agile, I don’t know what does.
While this did not solve all our problems, it did help out our team’s productivity in several ways:
- Our documentation was purposeful and immediately actionable without spending excessive amounts of time.
- It reduced our time spent on stuck on problems which are easily solved through visualisation.
- It provided a reliable, peer-reviewed source of reference.
- It encouraged collaboration and communication between the team by splitting up the work amongst all team members.
How to make it work for you
If I have successfully managed to convince you to give this style of documentation a shot, here are some essential points to remember to get the most of your agile effort:
Equal effort, equal ownership – Allow all your development team members to work on your document and take collective ownership of it during the sprint. This has the dual benefit of reducing each member’s individual workload while encouraging a sense of collaboration and responsibility among team members.
Document iteratively – Just like agile development, allow your documentation to build up organically over time by the collective efforts of your team. The collaboration and constant review and update cycle will keep documentation up-to-date, relevant and accurate.
Document as late as possible – For the most part, you should be documenting as late as possible, just before you require it. This will keep your documents highly purposeful and immediately actionable.
Keep it concise – Keeping it simple and straightforward is an excellent idea because writing longer, more complex documents are often more error-prone, and can take away valuable time. Trust that others in your team will pick up where you left off.
Avoid unnecessary overlap – Your document should mostly be highly focused on one topic or issue instead of a collection of many. If a long document consists of several similar topics in it, feel free to break it down into several small documents for each specific topic and label them as such for quick reference.
Ask yourself this repeatedly – What is the least amount of work I need to do to make this functional? This will ensure you are highly focused on what you must-have instead of what is nice-to-have. This mindset is central to making agile documentation work.
Conclusion
Keeping the above tips in mind, I’m sure that documentation will quickly turn from “that thing you have to do” to the thing you want to do to get optimal results.
Stay tuned for my next article where I will cover the Pomodoro technique, and how it can supercharge your and your development team’s productivity.