Loading...

Documenting Interfaces

Darcy Clarke - @darcy

Some things about me

  • @darcy
  • - Developer
  • - Designer
  • - UX Advocate

On behalf of Canada,
I'm Sorry...

That said...

Documentating Interfaces

What's documentation?

Documentation

  • Form of Communication
  • Historical Reference
  • * Educate
  • * Inspire

Documentation Types

  • Concept
  • Tutorial
  • Reference

* Reference is the
bare minimum

Good Documentation is:

  • Concise
  • Descriptive
  • Standardize
  • Easy to maintain

*Goal*
Big win with little effort

History

Lack of documentation...

Confusing or wrong documentation...

Why wouldn't I document?

  • Realtivity
  • Transparency
  • * Investment
    • * Thought
    • * Time

Present:
Project stakeholders

Or...

Workflow

Deliverables

Going further...

Fantasy Interactive

Teehan+Lax

Dribbble

Don't refelect reality

We need living documents

Is anyone else, or any other community doing this right now?

Foundation foundation.zurb.com

Manually update

EmberJS emberjs.com

BackboneJS backbonejs.org

Natural Docs naturaldocs.org

PHP Docs phpdoc.org

Tom Doc tomdoc.org

Comment 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
  */

What about UI?

UI / UX Reference
Documentation Requires

  • Context
  • Visual Queues
  • Multiliple languages

Key: Focus on CSS

CSS

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

The wild west

A Solution

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 - Repo warpspire.com/kss

KSS - Example warpspire.com/kss

KSS - Pros

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

KSS - Cons

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

Can we do better?

Documented Style Sheets

What is it?

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

DSS - Pros

  • * Flexible

Flexible?

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 - Parameter Defaults

  • Name
  • Description
  • States
  • Markup

DSS - 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 Commenting

/**
  * @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, "$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

We need you!