Who writes functional specifications and how to track what has been done in a clear and effective manner [closed]

Question

Background:

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:

1. 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.
2. Suffered from debating how something should be designed without actually resolving the issue before moving on.
3. 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.
4. 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. :)

• https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/

• Example: https://www.joelonsoftware.com/whattimeisit/

Other good threads:

• https://softwareengineering.stackexchange.com/a/34366/214079
• https://softwareengineering.stackexchange.com/a/49768/214079

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?

1. 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?

2. 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.

Answer 1

Getting the specs is only one part of the story

Let's illustrate the problem from an other angle. I'm working on financial systems. Finance and accounting is heavily regulated, so functional specifications are a must.

Since the beginning, we write functional specifications for everything that we develop. When it's something new, it's straight forward: based on the user requirements, you imagine the best solution, specify it, and get it reviewed and approved by the users. And yes, it's MS Word.

Keeping the specs up-to-date is the real challenge

Every living system will evolve. So now come the first software change requests and hence spec changes. Several options were tried in our team:

1. Track changes in wording: At first, we used MS-Word's track changes. Unfortunately, at the second change of the specs, it becomes difficult to say what track change was implemented and in which release. After all, edits in the text can't be mapped one to one with changes in the software. After the third change, all this colored or striken through parts are an unreadable mess. Not speaking of sometimes required stylistic rewording, just to be able to insert an additional sentence in the middle of a paragraph.
2. Specify changes ("deltas"): We then went to specify each functional change separately. The huge advantage, is that you can focus on the sole change, without worrying for what was already written. This results in compact specifications, no unnecessary rewording, and perfect traceability between specified changes and the corresponding implementation. The major issue here, is that after a while you'll lose the big picture: to know for sure what the software is supposed to do, we need to go through the initial spec and all the successive change specs. However painful this might sound, newcomers (and auditors) always find the info they are looking for. Isn't this the main goal of these specs ?
3. The spec as an artifact to update: The shortcoming of the "delta" approach can be addressed: you may benefit from the efficient approach of specifying the changes, but also add as part of the definition of done the update of the initial spec. So the revised spec that gives the current picture would be a deliverable of an iteration. Would we start from new, would we adopt this third approach ! Unfortunately we have already too many change specifications and we have not enough resources to retrofit all them. And as said, the main objectives are already met.
4. Use Case 2.0 and user story mapping are another approach to functional specifications. Interestingly, both identify successive "slices" that will be delivered. Here is one way of achieving it in JIRA. This could allow to use your JIRA stories as single source of truth for the specs AND for monitoring of what's implemented and how. Unfortunately it'll still be difficult to address changes other than with new stories. This will bring you back to 3.

Is the solution a better tooling ?

I think that the question is really a question about the approach. In my opinion, the tooling question is a false question:

• Instead of MS-Word, we could have used Confluence or a similar wiki tool. We'd have the advantage of not having the messy track changes. We'd always be able to find who wrote what, and compare current situation to a previous one. But still, there'd be no guarantee of a clear map from changes in the functional wording to changes in the implementation (unless you link every second sentence to JIRA issues; and this would be painful to read).
• You could think of a requirement management tool. But functional specifications (description of a solution) are not necessarily requirements (description of a need or a constraint). Furthermore, these tools tend to produce long textual lists of detailed items, which do not necessarily allow to grasp the big picture more easily than other approaches.
• So basically, MS-Word will do the job. But you have to manage versions of each specification. For this you may use either a filename convention, or, more reliable, any document management system that supports version management.

Conclusions

Looking at your situation, it appears that your way of working fits the needs but that you'd also value the spec as a desirable output of the implementation process for maintenance and team management purpose. So add version managed specs to your process, and sync the version management with your release management.

Who shall be in charge ?

Difficult to tell without knowing the context. In my team, we have domain experts. Each domain expert is responsible of the solution proposed to the user of his/her domain.

It can be a product owner, a project manager, a business analyst, a software engineer or a developper. The key here is not the role but the responsibility of doing it, and the communication skills: it must be someone who works closely with the users (e.g. gathering requirements, discussing stories, negotiating alternatives, etc..) and who is good at writing using "business" (aka domain) language.

Note: The term "program manager" might be misleading. In general, a program manager supervises several projects and is rarely him/herself involved in one of the project to write specifications.