Ask DN: Let's talk about specs/functional requirement docs.

4 years ago from , Founder at LayerVault

If you write specs or functional requirement documents, how do you format them? What do you put in them?

It's an area of deep interest for us. I seek The Perfect Spec™, a holy grail which is both super useful and informative while not being a pain in the ass. What does it looks like?

Let's discuss.

10 comments

  • Sabih MirSabih Mir, 4 years ago

    Miner's approach seems way too exhaustive for small teams that are quickly iterating on a product. It's a bit old school. I used to do specs like this and they were extremely time-consuming and were never used as intended by the people who were supposed to reference them. That was when I was consulting though, so my time was their money. Now back on the product side, it's a time suck I can't afford.

    There is a magic balance of documentation and design that needs to be available for posterity...and LayerVault's timeline is a good step towards this — may be allowing some way to indicate what was "shipped" in the timeline of a design? My current solution is a more visual/high level spec that explains the goals of each screen and has a semi-final design next to it, all in a Google Doc. I try to update it as we make decisions during product development so we at least have some history of decisions made on the ground.

    But that, also, isn't perfect.

    2 points
  • Jordan BorthJordan Borth, 4 years ago

    Wilson Miner has has a pretty cool approach: http://dribbble.com/shots/1205599-Baby-Log-Spec/attachments/160426

    I'm super interested in this stuff as well. I've tried many approaches but none meet The Perfect Spec™ as I so desire as well. I'm working on an implementation/spec doc now for an upcoming Mac app we're building and am using Sketch to layout, show dimensions/spacing, etc. I'll post when it's further along.

    Thanks for starting the discussion, hopefully we can get some good examples. How are you currently formatting and arranging your docs, Allan?

    1 point
    • Allan Grinshtein, 4 years ago (edited 4 years ago )

      Everyone involved in the project hammers on the same document. We use a wiki in GitHub that's basically formatted as such:

      Project Name

      Project summary

      Goals

      Goals and reasoning

      Requirements

      • Task -- Why
      • Task -- Why
      • Task -- Why

      Implementation details

      • High-level task -- Link to mockups -- Link to GitHub issue
      • High-level task -- Link to mockups -- Link to GitHub issue
      • High-level task -- Link to mockups -- Link to GitHub issue
      1 point
      • Nikhil NNikhil N, 4 years ago

        That's a neat template, Allan. Definitely and shamelessly going to copy this one. wink

        I'm curious about how do you'll keep a track of who added/modified what? Or does that quickly become irrelevant as you'll start working on the tasks?

        0 points
    • Nikhil NNikhil N, 4 years ago

      That's an incredible example.

      But to think of it, such docs would only be created upon finalising the window (as in this case), right? To do it with every change would be awfully exhausting.

      0 points
  • Robb SchillerRobb Schiller, 4 years ago

    It seems overkill for anything outside of a shared markdown file. GitHub repo wiki's seem perfect for this. However, I think The Perfect Spec™ isn't so much a complete spec outline as much as a rough system for organizing how to put together, or take apart a constantly changing spec doc.

    Was thinking about this a few months back, in light of a Karl Gerstner quote -

    "The difficulty lies in finding the balance between maximum formality and maximum freedom, or in other words, the greatest number of constant factors combined with the greatest possible variability."

    So I wrote down some product dev organizational ideas and called them Cheeseburger - https://github.com/FuturaIO/cheeseburger

    1 point
  • Marco SousaMarco Sousa, 4 years ago

    Specs are indeed time consuming but they are also documentation that can be accessed and used by fellow designers and engineers later on the project, whereas the 'sit-with-engineer' approach will keep all the information and understanding of the product locked with 2 or 3 people. The sweet spot of how much detail to add on specs will always depend on each specific team and designer. One approach is to iterate quicker on the pure visual design phase and use the spec creation phase to clean up designs.

    1 point
  • Victor MarkVictor Mark, 4 years ago

    I use Sketch to spec now, as they have the nice cmd, alt, shift function... then I take a screenshot using Stitch...

    I wish there was a way to view all the specs at once as stated in this feature request: https://bohemian-coding.tenderapp.com/discussions/sketch-suggestions/5607-suggestionquestion-about-spacingspecing-mode

    1 point
  • Matthew WarlandMatthew Warland, 4 years ago

    This is extremely handy for specs: http://www.specctr.com/ if you work in Illustrator.

    Functional requirements documents are mundane, drool documents that can make you die a little inside. http://www.fivesimplesteps.com/products/a-practical-guide-to-managing-web-projects is a fantastic book which tries to lay out a few alternatives.

    0 points
  • Ryan TeuscherRyan Teuscher, 4 years ago (edited over 3 years ago )

    Our team discussed working on a SaaS product a few months ago focused on specs. Ultimately, we decided it felt a bit like a feature of LayerVault. Looks like we might be right :)

    Design documentation has rightly become lighter as we move to code faster, and as the products / websites / apps themselves become the best form of documentation. However, I don't think we'll ever fully get away from some level of documentation, nor should we. Our vision of the future was a service for product managers to create high level product plans and roadmaps, designers to contribute thoughts, ideas, flows, mocks, and interactions as efficiently as possible, and engineers to get what they need right when they need it.

    • The Perfect Spec™ would be a tool where engineers could provide feedback to designers, and perhaps even collaboratively contribute (write) the specs for a feature or product.
    • No more pixel spec'ing by hand. Automate measuring abilities, color picking, and perhaps even css rule generation.
    • Instead of creating motion studies for standard interactions, you'd have a library of interactions displayed as animations that a designer could select from to include in the spec.
    • As the spec is updated, designers would have the option of notifying engineering of what they changed, and there would be an auto-generated change log.

    We'd love to see something like this come to fruition.

    0 points