0

TL;DR: We need a web based system that can integrate with Jira Issues to see what has been done and not.

Requirements:

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


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.

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. :)

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.

Problems:

  • 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
  • You need a tool that lets you write a functional specification that has links to JIRA? Did I understand correctly? – Nicolas Raoul Jul 19 '18 at 7:50
  • @NicolasRaoul That is correct. We have been looking at Confluence but I would like to know if there are other tools that are better. The documentation will be iterated quite a lot over a long period of time. – Ogglas Jul 19 '18 at 8:00
2

Your company's working methodology (non-waterfall) suggests that a wiki would be the best tool for that.

  • First, you will need to import your existing specification into the wiki.
  • Then at each evolution you will edit the relevant pages to add/remove/modify functional descriptions and requirements.

Merits:

  • Efficiently keep the specification up-to-date (wiki means "quick" and indeed nothing beasts its easiness and speed)
  • Versions can be compared if needed.

Since you are already Bitbucket, you already have one for free. I am not sure how finely you can set read/write permissions, though. If you have money you can get Confluence, which will also fit well into your JIRA/Bitbucket environment:

When knowledge flows freely, ideas grow and teams evolve. Confluence is the wiki software for today’s modern team

https://www.atlassian.com/software/confluence/why-wiki-collaboration-software

| improve this answer | |
  • Yes, Confluence it was. I couldn't remember the name (doo, and Ogglas even mentioned it! Too long a post indeed :), so you beat me to it :) And agreed, that should perfectly match Jira + Bitbucket – completing the "Atlassian Suite" Ogglas already uses. – Izzy Jul 19 '18 at 9:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.