I'm a UX architect working in house. In a nutshell wireframes are provided for our projects. We use JIRA as a way of tracking projects and confluence to document and archive them. Emails seem to be a way of things getting lost and unable to find when convenient.

One big thing that seems to be a problem within my team is documenting rationale. It's tricky where this should go without getting lost. It seems that confluence could be a good place for this, but I'm trying to figure out the best structure to do so.

Does anyone have any advice when it comes to documenting rationale and also conversations that have influenced big decisions?

  • Unfortunately this question is too broad for UX.SE, because you are asking for advice on 1. how to document conversations/rationale effectively, 2. what system to use, and 3. where to place and organize it. It would help if you narrowed your question, because each one of these is a considerable question in it's own right
    – tohster
    Commented May 13, 2015 at 16:23
  • I disagree with tohster here, as I see the question as primarily being about how to documenting the rationale. The system to use and where to organise it are side issues that may or may not be dealt with in answers. Either way, I find it a useful question about a real UX issue.
    – JohnGB
    Commented May 14, 2015 at 13:36
  • Hey Tohster. My issue is with the documentation. I was laying down the context of the technology we have in place to give you a better picture of my sceneario. I was just trying to indicate this in order it to potentially be relatable to other people on this forum. That way I can get the best answer to my situation. Sorry if there is too much in my question :) Commented May 14, 2015 at 14:55

4 Answers 4


I'm currently going through a similar learning curve with Confluence. At this point I'm dumping all wireframes into a folder named "UX Docs" and building out pages separately from that collection. As I write a doc page up, I insert the image into the page. This keeps all wireframes in a central location but also ties them to the appropriate pages.

These wiki style pages also have a comments section that allow for tracking discussions. The content can be commented on inline and Jira Issues can be opened based on highlighted content as well.

I'm still playing with this tool set I'm not sure if this is the best way to approach docs, but it's working for me for the time being. It let's me write through steps of UX and get feedback from the Dev team in early low fidelity stages. Then when higher fidelity mocks come forward, I already have some buy-in.


Have you considered the Atlassian marketplace? They've got some plugins and there might be one for your e-mail software to quickly upload e-mails to Confluence: https://marketplace.atlassian.com/

My team experimented with Bootcamp for awhile also. I really liked it, the interface is simple and easy for anyone on our team to learn. Lets you upload wireframes, add comments/feedback, as one example.

Verbal conversations are a different matter...no software's gonna be able to help with that (unless you find an audio recorder app and have the thought (and permission) to turn that on beforehand? Perhaps during a scheduled meeting). Try to take notes during or immediately after, then document as best you can. We always have an assigned notetaker during our meetings.

The rest comes down to human effort and management. It's important to stress to the team how critical documenting rationale is. Then actually DO it. Software gives you the tools, but people need to use them!

  • Thanks Rachel. Yes I agree with you it all comes down to the people. I think I'm just trying to see what other people do that is successful and then meet with my team in order to implement a way of documenting. Commented May 13, 2015 at 14:56
  • For my team some of it is self-evident. "If you take the time to document now, it will make your life 10x easier later." That can be a powerful motivator. Having an assigned notetaker has helped us. As soon as we are done with a meeting, a notetaker would type up summarizing notes into Basecamp and notify others to add thoughts. The notetaker would also have the ability to assign action items to our different employees if something could be handled immediately. Since our notetaker was our COO, she had the rank to get people to pay attention to use the system. That was my experience.
    – Rachel9494
    Commented May 13, 2015 at 16:05
  • Yes I find it tricky when presenting to our stakeholders and having to make notes at the same time. We don't have project managers so there is no one apart from my self able to take notes during the meetings. Commented May 14, 2015 at 14:57

If you're using JIRA, you can use SourceTree to document projects and track changes for Git and Mercurial. I think this is a very good question and probably something that hits us most of the time, because we need to work with systems we're comfortable with, then we need to work with systems the client is comfortable using. Personally, I like to use a combination of GitHub with InVision and Slack, but right now our studio is using these combinations with different clients:

  • JIRA + Source Tree + InVision + mail
  • custom developed documentation repo (client side) + Slack
  • GitHub + InVision
  • GoogleDocs + mail
  • Slack only with documentation as requested

The point is: I don't think there's a single answer to your question, because you can see all of the options above (and there are many more!) actually have their own perks, so you can track documents, screens, conversations, communications and so on, depending on the combination of services you use. And once you find the perfect method for your needs, one client may tell you to use something different. This is specially true in big companies where they have internal systems.

However, there's something we always do, specially with coding: comment absolutely everything and write clean code with references. And in design, you can add notes to PSD/AI, or add comments in services like InVision which also allows you to create some simple UX behavior mockups (Build Mode) or keep track of changes (History Mode)


Most of the front-end design/development frameworks usually include some explanation or rationale about the thought process involved in coming up with the framework. So in the same way I guess you should provide the rationale in the same proximity to where people would access it. However, there are still a lot of factors when considering how it should be done.

Some thoughts and ideas here (not sure if it constitutes an answer):

  1. Self-evident documentation - this can be achieved by putting it together with the design framework that you use and/or modify. Lots of work upfront but much less work later down the track.
  2. Document-as-you-go - this requires some effort spread across the project, and can be detached from the design and implementation frameworks.
  3. Document when asked - this requires no effort upfront but leaves a lot to do in the end (or maybe no work at all if not asked/required).

Ideally you should detach the documentation process from the design/implementation process (because it is another task/process) so that there are no dependencies created between each of the other processes if there are going to be changes. However, in this less than ideal world you can take any of the above strategies and then work out how to fit it into your current workflow.

My suggestion is to aim for somewhere between 1 & 2 (I highly discourage 3), and that way you can probably adjust the time and effort depending on the project schedule and constraints. No matter what tool you choose, it won't solve any problems that gets introduced due to poor communication/documentation standards/processes. If done well and you use JIRA, it is possible to have a nice integration that captures all aspects of the project in one platform, but then you run the risk of limiting yourself to that one solution, so choose wisely.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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