Documenting Rationale

Question

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?

Answer 1

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.

Answer 2

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!

Answer 3

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)

Answer 4

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.