What I can expect from this post: A DevSpec (development specification) is a simple, straight forward and short document that can be used to communicate work that needs to be done in an efficient and condensed way. We will look at benefits, a template and an example. Let’s go.
Software Development is hard work. Especially in smaller teams where processes have not really been laid down yet. It can be even harder when the environment you work in is a bit chaotic. Sure it can be interesting, there is always something new and different. However in order for things to go smoothly order is often required.
I find that developers generally have a great sense of finding the order in chaos, but sometimes you need to have a tool that can assist you. One such a tool is documentation. Ok there goes half my audience, and shortly after this sentence the rest will leave: Documentation is important.
Documentation can be a grind to set up, but the benefits outweigh the trouble in the long term. Let’s say you work in an environment where the goal posts are constantly moved, the requirement is constantly “updated” and the client is never happy with what they get in the end, well in this case a development specification can be a great tool.
“Isn’t it the BA’s job to do documentation?” Fair question, but the reality is, there won’t always be a BA, there won’t always be a PM or even someone who does project planning, sometimes you will work in the wild west where guns are shot wildly in the air. This is your opportunity to be the shining light, the beacon of hope and the leader needed in troubling times.
Lets look at the benefits
So, what’s the benefit of this so-called ‘DevSpec’?
- To clearly identify the requirement before work starts
- To clearly agree upon the requirement, and work to be done
- To remove as much ambiguity at the start of development, thus removing possible blockers
- To help you think through the process, thus providing you the opportunity to provide a much better crafted solution
- It will also provide you with the goal, how will you know what you have done is right and how can you test it
Naturally we tend to think that this now has to be 100 pages of academic literature with schematics, diagrams and addendums to addendums, but this is not necessary. We only need a simple* document that will explain 3 things:
- What needs to be done
- How will it be done
- How do we know it was done correctly
Anything extra is purely up to you, it is your document, if you want to add a diagram, go for it, as long as it is useful and communicates clearly to whoever is reading it.
Where to start
I have heard it said that the best tool for the job is the one you are most comfortable with, but I have a template that might be of use to you if you don’t know where to begin:
So how do I use this thing then? Let me add some detail into each section to give you a bit of a description:
This looks scary…
“OK WOW, that looks like a LOT of work, when will I find time for something like that?” – Another fair question, but remember, you are already doing all this in your head. Now we are just putting it on paper and getting it validated before we start with the actual implementation. Implementation in this sense is writing the code, doing the configuration, doing whatever needs to be done. Also, remember, this is your document, you can add in as much, or as little detail as you want, as long as it is helpful.
Another benefit of this is tracking. Why was a piece of work done, when was it done and why was certain business logic implemented. Often code comments are vague and understandable to the person who wrote them, but not necessarily to other team members. The DevSpec can help address that problem by providing you an insight into why a piece was developed.
Additionally, it also often helps to know what you need to do before doing it. Sure you might need to sit and fiddle with a problem, but at least the bulk of issues are identified beforehand. This naturally also helps you to do better time management, and it gives your manager a clear indication that you will be, or are busy with.
Give it a try, you don’t really have anything to lose. In the below section I will be going through an example of how to set up a DevSpec. So if you are all set, thank you for reading!
Looking at an example:
Scenario: We are working on a project where users are capturing data on rain around the country. The user wants to see a small daily report that shows the date, area and amount of rain for that date (per area).
The DevSpec will look something like this:
Addendum A: Wireframe
It is important that you make the DevSpec your own. It’s a tool that should help you, its not supposed to become a chore or to be mindless admin, that is not the point at all. Instead, it should help you solve the problem, communicate the planned work and what you will be doing. It should help you to clarify the requirement with your client to avoid rework.
Got any feedback? Post it in the comments. (if there is comments on our blog lol – still sorting out the details)