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?


This is a regular problem in organizations, and there are frankly a lot of solutions. Atlassian, for instance, uses Jira as the project management tool and Confluence as the connected service for documentation that is associated with related tasks. There are a lot of options here.

That said, the main challenge I see here isn't how to organize it so much as it is to streamline the documentation process to ensure that all parties (UX, Product, Engineering, QA, etc.) all follow the same path so that the results are in the positive. At the last two companies we did this pretty simply: structure all documentation and data so it's freely available, and connect to given specs, tasks, or other documents as needed.

Then again, both of those companies were fairly small (~10 employees, ~60 employees with connected team of 10). As the team sizes get larger, this method becomes more cumbersome as it does require management or else documentation and specs get stale.

That said, Agile teams work with this practice in general because each team is devoted to managing that spec, be it for a specific feature or an entire product. The variation depends on how your team(s)/company operates and the tools you currently use. Here are some pointers from my own experience:

  • I've never known an internal wiki to work without at least two people taking responsibility for ensuring that it's up to date
  • Standalone products like Word are bad unless the entire company is using it in a shared way, aka everyone's got Office 365, and everyone abides by that rule and you don't have some people using Gdrive and just transferring everything (which leads to a lot of user error and missing pieces)
  • Something that's connected to your project management tool isn't necessarily more helpful; I've seen this happen often, where it's either more complicated to handle or the staff isn't available to keep it up to date
  • Finally, if the functional specs are kept brief, the rest tends to fall in line
  • Thanks for sharing your experience here. We currently have instances of teams that use some combination of the tools you cite. I had no reason to believe there is some "magic bullet" solution for this challenge, but continued to hold out hope. I still assume some significant manual management is required, coupled with process changes that team members are willing to adopt.
    – yawitz
    Jan 23 '17 at 23:27
  • Yeah there've been some interesting conversations about toolsets and applications, both here and elsewhere. I typically recommend finding a solution that requires no tools (since it'll have to work within the team), then find the tools that fit closest to that pattern. That's always worked for my teams and anyone I know that has used that method, though it does require everyone agree to the chosen method and then sticks to it.
    – Jamezrp
    Jan 23 '17 at 23:33
  • Agree with and appreciate your comments, @Jamezrp. I expect that the challenge will be mostly behavioral, as people tend to cling to tools and methods they are familiar with. I'm intending to demonstrate the value of introducing some new methods and process, but want to understand and align with current habits as much as possible. (So I suppose a contextual inquiry will be part of this overall investigation.)
    – yawitz
    Jan 25 '17 at 2:04

This is a common problem for when you run two documentation in parallel. The risk is to have outdated links between the two.

In practice, they refer to these two documents in parallel, switching back and forth to develop a full understanding [...]

Let's assume that there are two different teams maintaining each document and that the new system must be able to:

  1. Reference one another
  2. Being maintained
  3. Easily available and shareable

I see two possible solutions.

Short term: a common parent

You may list the functionalities in a new document in a very light format to ease readability and maintainability. This document becomes the new reference and provides the links between the two documents. You are more likely to prevent outdated links with this solution as the two teams are only concerned by their document and the source one.

Long term: everything in one place

This a pattern I have noticed in various context: writing notes, tasks, calendar events, rules... If a system detains information for a common purpose across different areas, it is not maintainable. I would recommend merging all the documentation into one place. But this solution obviously needs more time and effort to try and iterate over.

  • Thanks for your thoughts. Yeah, both of these models have been discussed. Re: your short term suggestion, unless there is some tool that helps all team members manage end enforce such a model, I would expect that someone would need to own and manage the master document (keeping references to child documents up to date). For your long term suggestion, that would require some behavior changes on the teams' parts (which may need to happen anyway, for a variety of reasons).
    – yawitz
    Jan 23 '17 at 23:41

I would suggest going for the Long term approach of @asiegfried

In our team, we use Zeplin as a common ground. After the design is created in Sketch, the mockup is uploaded to cloud. People in the team get access to it.

  • the mockup gets updated, URL stays the same
  • the developer gets the rough CSS, so no need to write the specification for UI
  • every team member can leave the comment and tag other people in it
  • it's possible to check the previous versions of this document and track the changes.

I've also tried to work with dropbox paper on the freelance projects. It's very convenient when you have the working files in dropbox as well.

In my current work, we use Jira + Confluence, but it's easily becoming messy.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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