Documentation Principles & Procedures

Documentation Principles and Procedures

JS

View AskNature's JSDOCs

All Javascript is automatically documented as it's created via JSDoc. We abide by JSDoc commenting guidelines to continuously create clear and concise documentation every step of the way.

API

AskNature's API is available for public consumption and grows continuously to expose the full suite of CRUD functionality that is (or may be) possible. We write and parse our API documentation with API Blueprint and use an Apiary site to mock up and document the API. Calls are expressed in the native form we use in AskNature, as well as RESTful equivalents.

CSS

View AskNature's Living Styleguide

AskNature's interfaces use Bootstrap for layouts and styling. As much as possible, layout and styling should stick to theme-agnostic code so that themes may be swapped and/or updated over time.

For the inevitable exceptions to that rule-of-thumb, we abide by several syntax and organization standards, as well as facilitating the production of living style guides via KSS:

1. We utilize SCSS, which goes through an automated translation and minification process on every build.

2. We follow the Knyle Style Sheets (KSS) guidelines for organizing, formatting, and documenting blocks of code. The link above provides the full guidelines, but the basic format looks like this:

// 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.
a.button.star{
  ...
  &.star-given{
    ...
  }
  &.disabled{
    ...
  }
}

As recommended, over time we will evolve an organizational structure that is flexible, but rigid enough to be machine processed and referenced inside of documentation.

3. We utilize the block, element, modifier (BEM) methodology for naming CSS classes, following this pattern:

.block {}
.block__element {}
.block--modifier {}

• .block represents the higher level of an abstraction or component.
• .block__element represents a descendent of .block that helps form .block as a whole.
• .block--modifier represents a different state or version of .block.