0

Our organization has been clamoring for a more organized spec-making process. At the moment, we use a combination of UX Specs (created in a wireframing tool and published as PDFs), and Functional Specs (created in a writing tool, either a client such as Word or a hosted tool such as an internal Wiki). The two documents are created by separate teams on a project (the former by the UX Designer, the latter by one or more of the developers).

The key audience for this is the QA team. For now, the forms of these documents are working fine, but the fact that they are created, delivered and maintained separately is the problem. In practice, they refer to these two documents in parallel, switching back and forth to develop a full understanding of how the product they are testing is supposed to work. I am exploring ways that they can be managed as an integrated set of documents. In an ideal world, the functional spec would be able to refer to parts of the UX spec, and show those parts inline.

I am about to do a deep dive to evaluate SharePoint as a possible platform for this, as I believe it supports linking between managed documents. (And there appears to be a way to link to a particular page within a given PDF.) This is still not as integrated as I would like, but may be the best available option. Has anyone here dealt with this issue before, and if so, can you describe how you ultimately addressed it?

NOTE: I have also asked this question over on https://ux.stackexchange.com/, but thought this community would also have some ideas to share.

Community
  • 1
yawitz
  • 9
  • 1
  • 1
    It is not clear what stops you from merging the two into one. Yes, it is quite clunky to deal with pictures in MS Word, wiki should be easier to work with. – Vlad Jan 21 '17 at 08:25
  • The main barrier is social, i.e. resistance by participants to learn/adopt new tools that support an integrated document. My main goal in this topic is to identify tools that can reduce the friction and/or learning curve, it any such tools exist. – yawitz Jan 23 '17 at 23:47
  • probably your need to explain this 'friction', feels like it's the actual problem you are trying to solve. – Vlad Jan 24 '17 at 16:54
  • The "friction" here refers to developers' resistance to adopt new tools and process when what they currently use has been working for them. I can't really solve this, but instead need to demonstrate the value of adopting some new methods and process. The less effort required to switch, the better. – yawitz Jan 25 '17 at 02:10

1 Answers1

1

I've seen this interplay only with use cases referencing to prototypes when delivered together.

Instead of "System displays list of the goods" write "System displays list of the goods as per prototype[being link to the prototype of the list]". Now you have very powerful tool:

  1. Behavioural and design requirements are split but interconnected. (divide and conquer)
  2. You are free to reach any level of precision you need for each page, screen and GUI element. One prototype and link for simple non-interactive page, detailed specification for dynamic and crucial elements, including:
    • Prototypes of the list itself and of the entire page, in minimal support and most used resolutions each.
    • Positioning on the page and against other elements.
    • Description of initial state of each element - filters, sorting, checkboxes.
    • Description of how each label and each list values are taken. Is it hardcoded, taken from some configuration setting (you can link to it here), populated by some complicated algorithm explained in the use case.
    • All alternative and failure flows in the scenario may link to their own prototypes to cover any situation possible.

You can easily facilitate this in wiki or even MS Word, but settle on the process first.

Pay attention that having all the prototypes inline makes requirements unreadable and unusable. It is enough to have them one click away, previews on hover help as well. There are two typical scenarios: user needs some system behaviour detail and is not interested in the prototype at all; user needs prototype of some specific situation and not all others.

Vlad
  • 559
  • 1
  • 3
  • 6
  • Thanks for your thoughts here. I agree with your approach, but it would require some behavior/process changes on the part of team members. My goal in this topic is to identify any tools that can help streamline this process, before I move forward with any process change recommendations. – yawitz Jan 23 '17 at 23:50