Loading...

Documenting Interfaces

Darcy Clarke - @darcy

Some stuff & things

  • @darcy
  • Developer
  • Designer
  • UX Advocate *
    • * Panda Advocate
    • * Bacon Advocate

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

4 Times Platinum!?!

On behalf of Canada,
I'll take credit for...

Documentating Interfaces

What's documentation?

Documentation

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

Communication Mediums
over time

Lack of documentation...

Confusing documentation...

Avoid those situations

Present:
Typical stakeholders

Or...

Typical Workflow

Deliverables

Going even further...

Fantasy Interactive

Teehan+Lax

Dribbble

* Share

Concerns

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

Imagine a Eutopia

Documentation
Should Be:

  • Concise
  • Descriptive
  • Standardize
  • Easy to maintain

* Big win with
little effort

Who docs well?

EmberJS emberjs.com

Foundation foundation.zurb.com

BackboneJS backbonejs.org

Documentation Types

  • Concept
  • Tutorial
  • Reference

* Reference is the
bare minimum

Automation to the rescue!

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 - Example 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 - Cons

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

We're working on that . . .

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