Designing & Documenting User Interactions - San Francisco HTML5 MeetupLoading...@darcy

Designing & Documenting
User Interactions

A presentation by @darcy

Big thanks to Peter, Vanessa & Yelp!

SFHTML5 Meetup Survey

http://bit.ly/sfhtml5-2013

@darcy

Work

  • Co-Founded Themify
  • Fi (Fantasy Interactive), Jet Cooper, Polar Mobile, Say Yeah!, Playground, Blast Radius, Bnotions, Daily Challenge, Pinpoint Social, My City Lives, Viafoura, Flixel
  • Google, Microsoft, Nike, Samsung, Porsche, Ducati, Disney, Red Bull, CBS, Panasonic
  • jQuery, DSS, Frontend Developer Interview Questions, Watch.js, Repo.js ...

  • github.com/darcyclarke

I'm sorry...

What I do

* Holistic Problem Solving

  • Better understanding of goals
  • Better communication
  • Shared responsibility

My Last 12 Months

  • Progressive Enhancement
  • Feature Detection
  • Polyfills & Web Components
  • Typography
  • Standards & Accessibility
  • Responsive Images
  • Mobile Video
  • JavaScript Video Decoders
  • Open Source
  • * Documentation

2013

Designing & Documenting
User Interfaces

Focus on

* Experiences

Designing & Documenting
User Interfaces Interactions

Stereotypical Workflow

Stereotypical Stakeholders

Stereotypical Deliverables

Sketches / Paper Prototypes

Wireframes / Sitemaps / IA Documents

Photoshop / Illustrator Files

Website

If you've got budget and/or time...

Mood Boards

Style Tiles

Functional Prototypes

Going even further

Fantasy Interactive

Teehan+Lax

Dribbble

What's the problem with all
of these deliverables?

* Decentralized.

* Don't reflect reality.

* They're static.

* We need living
documents & documentation

Good Documentation is:

  • Concise
  • Descriptive
  • Standardize
  • Easy to implement
    & maintain
  • * Adds value

Bad documentation is:

  • Aloof
  • Confusing
  • Wrong
  • Hard to maintain
  • * Looses trust

Why wouldn't I document?

  • Project Life-Cycle
  • Team / Reach
  • Time / Cost

Challenges with
Interactive Documentation

Requires

  • Context
  • Visual Aids
  • Multiple languages

Examples of great
Interactive Documentation

BBC

Problems?

They're static

Examples of great
Living Interactive Documentation

Yelp

Starbucks

Github

How are they doing this?

* Static File Analysis

* Comment Block Parsing

Comment Blocks

/**
 * This is the description for my class.
 *
 * @class MyClass
 * @constructor
 */
/**
 * My method description.  Like other pieces of your comment blocks,
 * this can span multiple lines.
 *
 * @method methodName
 * @param {String} foo Argument 1
 * @param {Object} config A config object
 * @param {String} config.name The name on the config object
 * @param {Function} config.callback A callback function on the config object
 * @param {Boolean} [extra=false] Do extra, optional work
 * @return {Boolean} Returns true on success
 */

Key: Focus on CSS

Why CSS?

  • Has context ( pseudo classes/states )
  • Inherently visual
  • Bridges languages

Tools

KSS - Ruby Gem

warpspire.com/kss

KSS - Styleguide

// A button suitable for giving stars to someone.
//
// :hover             - Subtle hover highlight.
// .stars-given       - A highlight indicating you've already given a star.
// .stars-given:hover - Subtle hover highlight on top of stars-given styling.
// .disabled          - Dims the button to indicate it cannot be used.
//
// Styleguide 2.1.3.

KSS - Example

warpspire.com/kss

KSS - Ports

  • - Grunt-KSS (github.com/t32k/grunt-kss)
  • - Gulp-KSS (npmjs.org/package/gulp-kss)
  • - PYKSS (github.com/seanbrant/pykss)

KSS - Pros

  • - Dynamically generates an object
  • - Enforces structured commenting
  • - Encourages documentation of states
  • - Reduces redundancy
  • - Works with SASS, SCSS & LESS

KSS - Cons

  • - Strict
  • - Static sections
  • - Doesn't address context
  • - Doesn't addess inheritence

Documented Style Sheets

What is it?

  • A documentation tool
  • A style guide
  • A comment parser

DSS - Pros

  • - Dynamically generates an object
  • - Encourages structured commenting
  • - Provides api for custom detectors, parsers, templates
  • - Encourages documentation of states
  • - Reduces redundancy
  • - Works with any file (*)
  • - Seperated concerns

DSS - Styleguide

// @name Button
// @description Your standard form button.
//
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// @state .primary - Indicates button is the primary action.
// @state .smaller - A smaller button
//
// @markup
//   <button>This is a button</button>

DSS - Defaults

  • - Name
  • - Description
  • - State
  • - Markup

DSS - @state Parser

// Describe parsing a state
dss.parser('state', function(i, line, block, file){
  var state = line.split(' - ');
  return {
    name: (state[0]) ? dss.trim(state[0]) : '',
    escaped: (state[0]) ? dss.trim(state[0].replace('.', ' ').replace(':', ' pseudo-class-')) : '',
    description: (state[1]) ? dss.trim(state[1]) : ''
  };
});

DSS - Custom Parameters

/**
  * @name Button
  * @description Your standard form button.
  * @link https://github.com/darcyclarke/DSS/issues
  *
  * @state :hover - Highlights when hovering.
  * @state :disabled - Dims the button when disabled.
  * @state .primary - Indicates button is the primary action.
  * @state .smaller - A smaller button
  *
  * @markup
  *   <button>This is a button</button>
  */

DSS - Custom Parser

// Replace link with HTML wrapped version
dss.parser('link', function(i, line, block){
  var exp = /(b(https?|ftp|file)://[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/ig;
  line.replace(exp, "<a href='$1'>$1");
  return line;
});

DSS - Output (JSON)

{
  "name": "Button",
  "description": "Your standard form button.",
  "state": [
    {
      "name": ":hover",
      "escaped": "pseudo-class-hover",
      "description": "Highlights when hovering."
    },
    {
      "name": ":disabled",
      "escaped": "pseudo-class-disabled",
      "description": "Dims the button when disabled."
    },
    {
      "name": ".primary",
      "escaped": "primary",
      "description": "Indicates button is the primary action."
    },
    {
      "name": ".smaller",
      "escaped": "smaller",
      "description": "A smaller button"
    }
  ],
  "markup": {
    "example": "<button>This is a button</button>",
    "escaped": "&lt;button&gt;This is a button&lt;/button&gt;"
  }
}

GRUNT-DSS - Output

DSS - Future

  • - Chrome Extension to record events
  • - Playback events
  • - Sandboxed components

Things to keep in mind

  • * Holistic Problem Solving
  • * Focus on the Experience
  • * Centralize your documentation & resources
  • * Implement documentation tools that:
    • - Dynamic
    • - Easy to maintain
    • - Help communication
    • - Increase consistancy
    • - Add value