Loading...

Documenting Interfaces

Darcy Clarke - @darcy

Thank you!

Paul Irish
Cool dude or coolest dude?

Some stuff & things

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

WTF 11.5mb!!!!




I care . . .

but I don't at the same time

What's documentation?

We gots problems!

Communication is broken

A Typical Workflow



The invention of...
the Designer/Developer



Note: I'm one of these jerks

Information is siloed

New collaborators get lost

*Communication is key to learning new concepts*

Documentation Should Be:

  • *Concise
  • *Descriptive
  • *Standard
  • *Easy to maintain
  • *Doesn't effect your workflow

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 Documentation is hard:

  • *Requires Context
  • *Visual Queues
  • *Multilingual

Key: Focus on CSS

The wild west

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

KSS - Cons

  • *Multi-step process
  • *Commenting guideline isn't flexible
  • *Doesn't address context
  • *Doesn't addess inheritence

Can we do better?

long pause . . .

Documented Style Sheets

What is it?

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

DSS - Pros

  • *Single-step build process
  • *Flexible styleguide
  • *Template support
  • *Grunt.js Plugin

DSS - Cons

  • *Doesn't address context
  • *Doesn't addess 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>
  */