TL;DR: We need a web based system that can integrate with Jira Issues to see what has been done and not.
- Ideally a web application where read and write access can be given to different users.
- Normal services that we use cost around 10-20 dollars a user. If there is an awesome service but it costs more I would still like to know about it.
- Needs to be able to integrate with Jira Issues, support simple formatted text (SO editor would be fine), picture upload in text.
Would really appreciate if someone has been in a similar situation and found a good solution.
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.
Our initial solution:
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.
The biggest thing 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. Perhaps Confluence could work for this or are there any other good tools?
Even though the document has a Index and headings the document is growing very fast and can sometimes feel like a bit of a mess. We try to use a simple enough language, review the work and try to rewrite hard parts. I think this is due to the technical notes, open issues not yet decided, what text should be displayed where etc. The gut feeling is that there should be some software out there. A lot of companies that I worked with used Excel for a long time to write their issues but now nearly everyone has moved to Jira, Trello or other software.
Tools that we use today:
- Issue Tracker: Jira
- Wireframes, mockup & Prototyping: Balsamiq
- Product design & workflow: InVision
- Other products that we use and have available for the project:
- Office365 - Email, Calendar and Documents
- Bitbucket – Git version control and technical Wiki
- TeamCity – Build server (Will be switching to AppVeyor)
- OnePassword – Login credentials
- Slack – Communication
- Azure – Hosting
- Octopus Deploy – Deployment
- OneDrive, Google Drive, Sharepoint och Dropbox – File storage