Partial critique pass on v4 content

Author: nickawalsh

source/components.md

@@ -48,4 +48,6 @@ When determing whether a module is a Component or Structure, we find it helpful
 - Does this module depend on or extend other Components?
 - Is this module abstract enough to use in other projects without making significant changes?
 
+<!-- Nicktique: second line ('Does this depend on / extend other Components') sounds like a Structure -->
+
 If you answer "no" to any of these questions, the module in question is more than likely a Structure.

source/foundation/base.md

@@ -13,6 +13,8 @@ Base contains all of the tag-level settings for default HTML elements. These are
 
 We define `html` and `body` styles at the top, and then divide the remaining content into Block and Inline sections.
 
+<!-- Nicktique: font-family, font-size, and line-height can all be combined into one fun line. -->
+
 ```sass
 // *************************************
 //

source/foundation/config.md

@@ -28,6 +28,8 @@ If serving font files from a known path (e.g. your server), we include Bourbon's
 +font-face('OpenSans', 'OpenSansItalic', normal, italic)
 ```
 
+<!-- Nicktique: this might not be the best method for importing Google Fonts - I've been doing it in dev because of the simplicity, but there might be a better way. This type of import isn't a Sass import, so it's probably creating another HTTP request. -->
+
 When using web fonts from Google Fonts, or a similar service, you can paste their generated `@import` link into this section.
 
 ```sass

source/foundation/index.md

@@ -8,6 +8,8 @@ children: true
 Foundation
 ==========
 
+<!-- Nicktique: `the` appears too many times in this first paragraph -->
+
 As mentioned earlier, the Foundation represents the tools and materials at the ground level. This is the initial setup for your application. The Foundation is made up of:
 
 - Reset

source/foundation/tools.md

@@ -9,6 +9,8 @@ nested: true
 Foundation - Tools
 ==================
 
+<!-- Nicktique: this reads too much like a changelog; documentation should sound a little more 'sure of itself' - chiseled in stone, as it were, -->
+
 Since the last version of MVCSS, we've embraced the idea of presentational class names, and have included them as Tools in MVCSS v4. Simply put, Tools are presentational utility classes for usage within HTML itself. They're helpful when you need a specific style in a unique context, but can't justify creating (and naming) a new module or modifier to achieve the desired effect.
 
 ```html

source/index.md

@@ -13,8 +13,12 @@ CSS, for all its simplicity, is a difficult language to manage in large-scale im
 
 Keeping with the architecture motif, applications are split into three major categories: *Foundation*, *Components*, and *Structures*. If Foundation represents tools, materials, and the ground level, Components are akin to creating a window from those materials, and Structures would be a number of windows and doors creating a wall.
 
+<!-- Nicktique: not something we need for the initial launch of v4, but something visual here would really help drive the main structure point home. An illustrated diagram of the foundation -> component -> structure setup, perhaps. -->
+
 For a very early taste, here’s what a simple Component might consist of:
 
+<!-- Nicktique: we should pare this example down a bit, and perhaps even remove the variables. The structure is the most important part, so we want as few surprises as possible. -->
+
 ```sass
 // *************************************
 //

source/shared/_sidebar.haml

@@ -21,6 +21,7 @@
             - get_nested_pages(page.data.title).each do |nested_page|
               = link_to nested_page.data.title, "/#{nested_page.path}", class: (is_page_active(nested_page.url) ? 'sidebar-link sidebar-link--sub is-active' : 'sidebar-link sidebar-link--sub')
     .sidebar-nav-secondary
+      / Nicktique: this subheader is too close to normal links, the style needs a bit more differentiation.
       %h3.sidebar-label.mtl Meta
       - get_secondary_pages().each do |page|
         = link_to page.data.title, "/#{page.path}", class: (is_page_active(page.url) ? 'sidebar-link is-active' : 'sidebar-link')

source/styleguide/basics.md

@@ -18,6 +18,8 @@ Styleguide - Basics
 - Stick with classes instead of IDs for styling
 - Limit nesting as much as possible
 
+<!-- Nicktique: prefixed properties are alphabetized by their non-prefixed equivalent. -webkit-transition, -moz-transition, then transition, based on the `T`. -->
+
 ```sass
 // Example
 

source/styleguide/naming.md

@@ -74,6 +74,8 @@ After creation, elements that need a modifier will use the root class (`.btn`) a
 <button class="btn btn--a btn--l">A Button</button>
 ```
 
+<!-- Nicktique: using `--a`, `--b`, etc. in the examples is dangerous since we've moved away from that. This next sentence is definitely off. -->
+
 **Note:** appearance modifiers typically work best when defined in sequence (`a`, `b`) or via function (`cancel`, `submit`) as opposed to look (`red`, `blue`).
 
 States
@@ -119,6 +121,8 @@ Context
 
 We also borrow the idea of context from SUIT. Modularizing styles into self-contained units works well *most* of the time, but you’ll occasionally need a parent element to fall in line.
 
+<!-- Nicktique: we've been using this a lot more in the context of list items, that might be a better example to drop in. -->
+
 The most common case tends to be positioning context. If you have a dropdown structure that’s being positioned absolutely, the parent element should be (at least) positioned relatively:
 
 ```sass
@@ -172,6 +176,8 @@ Elements nested within a Component or Structure that need styling *based on bein
 
 For items in scaffolding, the Component/Structure name comes first, followed by a single hyphen and the subcomponent/substructure name (also in camelCase, if necessary). Where applicable, they can have their own modifiers, states, and subcomponents/substructures—more than two levels, though, typically means it’s time to refactor.
 
+<!-- Nicktique: a common misunderstanding with folks new to MVCSS is creating states / modifiers / etc. under a scaffolding item. An example of that might be helpful. -->
+
 Variables
 ---------
 

source/styleguide/numbers-game.md

@@ -22,3 +22,5 @@ Approach
 This setup should be a easier to grasp once we reach the Config, Tools, and Base segments of Foundation.
 
 **Note:** pixel values will occasionally be required to meet design requirements, especially with things like offsets. Try to use them as sparingly as possible.
+
+<!-- Nicktique: might help to weave magic numbers in here: http://csswizardry.com/2012/11/code-smells-in-css/ -->