How to document multiple interactions

Question

Is there a best practice on how to document complex or layered interactions like the ones used in the native Mail app of iOS8?

How is it possible to document in a clear way complex interactions and motion like:

1. Swiping to the right, the email item can be dragged for 20% of the viewport width revealing a button;
2. After 20% a rubber-band effect on the button slows it down, separating it from the swiped email element (still being dragged);
3. When the mail item passes 50% of the viewport width, the button expands again with a transition until it touches the mail item again, to signal that the operation in the button will be executed.

There are many subtle details in the transitions and interactions that make it hard to capture them all on a coherent, readable and understandable document.

I would like to see examples of documents used in a real work environments, that are quick to produce and clear to understand for designers, developers and testers.

---

Reference: http://youtu.be/vfP5IqarJAA?t=40s

Answer 1

I work with Axure most times and this is how I usually approach - in my every-day, real work environment - the realisation and documentation of complex interactions (like the ones you describe):

1. I realise the interactive prototype in Axure Pro 7.0.
2. I use the "Notes" functionality to add extra notes and details and make sure I give all the information needed to understand how I expect it to work.
3. I automatically generate the documentation using the "Generate Word Documentation" functionality.
4. I review the document and fix what needs to be fixed.

This is how a very simple interaction on an automatically generated specification document looks like:

As you can see Axure automatically lists all the interactions (and their details) associated to an element, including - in this case - action types (e.g., fade), duration (e.g., 300ms) and movement on x and y axis (e.g., -70,0).

The interaction in the example above is very simple and has no notes. Things can get much more complicated.

For instance, this is how the documentation for a standard component I use (input field with auto complete search) looks like:

So, going back to your request:

I would like to see examples of documents used in a real work environment, that by nature are quick to produce and clear to understand for designers, pms, developers and testers.

This are my answers:

• "documents used in a real work environment": yes, they're what I use in my everyday work
• "that by nature are quick to produce": I think that the automatic generation is time-efficient. You already have to create the interactions for the prototype, it's good to already find the on a document with no extra-effort.
• "are clear to understand for designers, pms, developers and testers": I'm not so sure about how "clear" this documentation can be considered. It's usually very clear for developers. It can be not so clear for UI designers and, sometimes, for PMs too. I think it really depends on the background of your team.

Extra thoughts:

• In my experience the combination of interactive prototype + documentation (including notes) has (almost) always been enough to describe and obtain the desired result. Sometimes it didn't work, but the problems where elsewhere (e.g., team motivation, insufficient technical skills, etc.)

• The same combination of interactive prototype + documentation has proven to be the most detailed and "safer" solution. Anyhow you give the team many pages of documentation to read, so it's not the agilest solution...(but again, you're asking for "a best practice on how to document" so I guess you need extensive documentation).

• The efficacy of an automatically generated document really varies depending on the context of the project. Most times it can be a good starting point or even a sufficient final version, while in some cases it's just not ok.

• The "Notes" and "Generate Word Documentation" are only in the PRO version of Axure. Double check you have this version.