In a project where I work as a developer we did not use a functional specification at first. We relied solely on technical documentation, issues in Jira and mockups/detailed design for accepted views.
This worked quite a long time but lead to some problems:
- Introducing new team members and bringing them up to speed. The system is quite complex in my opinion and has a lot of business rules. Onboarding new team members was really tedious. Even though we had technical documentation the functionality was not described from a combined technical and user perspective. Understanding business cases solely from design is very hard in this case.
- Suffered from debating how something should be designed without actually resolving the issue before moving on.
- Actual decisions were placed in our issue tracking software, executed and then gone. This meant that we did not get a complete overview of the functionality anywhere and what was finally decided. We still use Epics in Jira but it is hard to get a complete overview anyway.
- Texts that should be visible on the page where emailed to us, we created a issue and then fixed it. Updates were also sent via email and sometimes a new issue was created even though the first issue was still in To Do.
Introduction of functional specification
We therefore started to write a functional specification detailing what every view should do and look like in a shared word document.
The initial document is not completely from Joel Spolsky's blog but we have tried to cherry pick. Really good read even if it is nearly 18 years old when I write this post. Fun fact: I was 10 years old when he wrote it. :)
Other good threads:
This made everything easier to follow even though it takes time to maintain. However I still think there are some things that could be improved and don't feel 100% yet.
How to improve our approach and who should be in charge?
The biggest issue is tracking what has been done in the functional specification and not. What we do now is decide what should be done, update the functional specification since we see this as the single source of truth and then we create issues to match the specification. It would be really good to be able to link a specific view to Jira Issues. Given only the specification it is hard to tell what has been done and if there are issues created. How could this be solved?
Joel talks about the heroic program manager that should write the specification. He specifically says Don’t promote a coder to be a program manager. This is exactly what happened since our project manager is not that technical and he/she would otherwise be the choice for this. To avoid having a lot of people editing the document we have one on the client side editing and one one our side and they keep a close communication about what is being done. (Yes Joel says one author only but he also says sometimes you have to break the rules). Right now we are a small team of three developers and one project manager on our side. If the project manager were to write the specification it would still break Don’t have coders report to the program manager. Who writes the specification in your projects of similar size and does that work well? Any pitfalls you have learned from along the way is most appreciated.
Would really appreciate if someone has been in a similar situation and found solutions.
Remark: Given that questions about finding or recommending products or services is out of scope I created a question on Software Recommendations. If you think that using Microsoft Word is not a good idea, please write an answer there for what Software helped you write a good functional specification.