Confluence or Jira forms for storing design documents?
Asked by Julian Clements:

Hi - I am looking to migrate our standard Word design artefact to an electronic version and have been doing some research but rather confused over product seelction...

I can see there are add-ins for both Jira and Confluence for form creation (essentially I am thinking the current Word doc can be replaced by a form) so not sure which one I should be investigating.

Any help apprecaited (I am a new user to these products and looking for a steer to point me in the right direction!)

Julian.


Answers:
author: Julian Clements
body: Thank you all for your comments and advice, I will take some time out to go and play with some of these ideas, many thanks again.


author: Jochen Neuhaus
body: If you consider your singlee requirements as separate "artifacts" and want to manage a status for each one and relations to others and want to search/filter this data structure, I would recommend JIRA issues. You can still use confluence for landing pages that include (filtered) lists of these issues with the jira issue macro. Using add-ons, you can also enforce / check on proper linking on requirement artifacts as described by *Pam Weber* above

(Versioning of these requirement artifacts + landing pages is then a more complex issue, without an easy solution)


author: CJ
body: Hi Julian,

If you'd just like to create pages with a standard template with headings, tables, helper text, etc, then I find the standard Confluence 'Product requirements' page template a good place to start. You might be happy with how it works, or it might introduce you to a few macros that you will find useful in building your own template and structure.

I'm not sure what version of Confluence you have, but to add the 'Product requirements' template, you may need to click the \[...\] button next to the 'Create' button to see the list of templates.

When you add a 'Product requirements' template, it will create a page made from a template (the one you can edit immediately) and an extra page called 'Product requirements' (You'll see it appear on your side menu) which has a few useful macros:

\* Create from template - this adds a button to your page, so it's easy to add new pages with your chosen template.

\* Page properties report - This macro lists information on other pages as long as they match your specified requirements and use the 'Page properties' macro (it makes a bit more sense when you give it try!).

If you want to edit the templates, then you can do so in Space tools \> Content Tools \> Templates. And then find the 'Product requirements' section. Another thing you may find useful with the tempaltes is that you can add 'tempalte text' which is only visible to the person editing the page, so you can use it for instructions.

I hope that helps,

CJ


author: Pam Weber
body: *Example*

* *TestcaseABC* **validates** *Story123*
* *Story123* **is validated by** *TestcaseABC*


author: Pam Weber
body: You can also use the free **Draw.io** add-on in JIRA to add UML drawings (and many other types of drawings). It works very much like Visio.

We don't have Confluence, so we are using Stories in JIRA for requirements and attach Word documents if we need more detail or formatting than the standard Story. Eventually, I hope to add custom fields to handle the standard information included in most requirements so we can report on standard data elements across requirements. We also created a custom issue type for testers, so they can link their test cases to Stories with a **Validates/Validated by** relationship.


author: deonvanniekerk
body: Using Gliffy or Balsamic plugins can help bring more design artifacts into Confluence in case you need proper UML drawings or Screen mockups.


author: deonvanniekerk
body: Use the Gliffy plugin for your design artifacts. At leats you have proper UML capability to leverage there and can also do screen mockups. We use Balsamic plugin for screen designs as well.


author: Phil Parkin
body: In Confluence, you can use a custom template to ensure that users are presented with a common layout when they create the document. No add-ins required.

There is nothing to stop them moving sections around, creating new sections etc, once they are in Edit mode though. If you are happy to manage that, I'd recommend Confluence.


author: Shinjani Gaur
body: To create a template that is specific to a Confluence space you would need space admin permissions and to create, global templates that are available to every space in your instance of Confluence, you woud need Confluence admin permissions.

For storing design documents, I too would lean towards Confluence.


author: Julian Clements
body: Thanks for the response, a little more info... I am looking to migrate a paper based design requirements garthering document to a form based solution, the documents have set questions/headings that I will need to have available in the form based solution.

From what I am understanding from my research and your response, Confluence is more suited to this use-case but if I want to enforce some structure to the document (set headings, fields that need completing etc) I will beed to be looking at using one of the (many?) form add-ons on the maket place?

I am keen to understand more on the blueprints/templates options as these feel like a good option also? I have tried to look at my insdtallation but I assume it is all locked down for me at this time as can not see how to create templates/blueprints?

Sorry for all the questions! Your help is appreciated.


author: Nic Brough -Adaptavist-
body: I would personally lean towards Confluence for this sort of stuff. JIRA is an issue tracker, and Confluence a place to write and publish things.

Confluence even goes as far as having a Word import for helping convert existing documents into pages.

The downside of leaning that way is that JIRA is structured data, almost a "form" already, whereas Confluence is free format, letting you put anything what you want on a page.

I think the ultimate decision is up to you - if you're happy with the fields JIRA can offer, and they do everything you need for your form, then go with that. If you have complex process flows to model with them, you should be leaning towards JIRA as well.

Confluence is probably a better presentation layer for them (I can't tell without examples), as people can structure them in an easy to read shape, rather than be stuck with JIRA's screen layouts. But that unstructured thing may be an issue. You could try getting people to use templates and blueprints, which get them started with new pages of the correct shapes, but if you need to be rigourous about the non-content data you want to capture, you'll need to be looking at one of the forms add-ons.


Tags: jira