Merge pull request canjs#1313 from bitovi/1302-component-documentatio…

…n-fixes

Fix-up suggestions from the OS Contrib meeting, and add style guide to...

component/component.md

@@ -68,7 +68,7 @@ set on the component's scope.
 
 ## Use
 
-To create a [can.Component], you must first [can.Component.extend extend] `can.Component`
+To create a `can.Component`, you must first [can.Component.extend extend] `can.Component`
 with the methods and properties of how your component behaves:
 
     can.Component.extend({
@@ -114,7 +114,7 @@ you'll render a template with many custom tags like:
 
 ### Extending can.Component
 
-Use [can.Component.extend] to create a [can.Component] constructor function
+Use [can.Component.extend] to create a `can.Component` constructor function
 that will automatically get initialized whenever the component's tag is 
 found.
 
@@ -265,7 +265,7 @@ only renders friendly messages:
 
 ## Differences between components in can.mustache and can.stache
 
-A [can.mustache] template passes values from the scope to a [can.Component]
+A [can.mustache] template passes values from the scope to a `can.Component`
 by specifying the key of the value in the attribute directly.  For example:
 
     can.Component.extend({
@@ -302,7 +302,7 @@ Because the attribute value would be passed as the value of `greeting`.
 
 ## Examples
 
-Check out the following examples built with [can.Component].
+Check out the following examples built with `can.Component`.
 
 ### Tabs
 
@@ -424,7 +424,7 @@ its sub-components:
 ## IE 8 Support
 
 While CanJS does support Internet Explorer 8 out of the box, if you decide
-to use [can.Component] then you will need to include [HTML5 Shiv](https://github.com/aFarkas/html5shiv)
+to use `can.Component` then you will need to include [HTML5 Shiv](https://github.com/aFarkas/html5shiv)
 in order for your custom tags to work properly.
 
 For namespaced tag names (e.g. `<can:example>`) and hyphenated tag names (e.g. `<can-example>`) to work properly, you will need to use version 3.7.2 or later.

component/scope.md

@@ -7,8 +7,8 @@ instance is initialized with values specified by the component element's attribu
 
 @deprecated {2.1} In 2.1, [can.stache] and [can.mustache] pass values to the 
 scope differently. To pass data from the scope, you must wrap your attribute 
-value with `{}`. In 3.0, [can.mustache]
-will use [can.stache]'s syntax.
+value with `{}`. In 3.0, `can.mustache`
+will use `can.stache`'s syntax.
 
 @option {Object} A plain JavaScript object that is used to define the prototype methods and properties of
 [can.Construct constructor function] that extends [can.Map]. For example:
@@ -24,7 +24,7 @@ will use [can.stache]'s syntax.
       }
     })
 
-Prototype properties that have values of `@` are not looked up in the current scope, instead
+Prototype properties that have values of `"@"` are not looked up in the current scope, instead
 the literal string value of the relevant attribute is used (like pass by value instead of pass by reference).  For example:
 
     can.Component.extend({
@@ -264,14 +264,14 @@ Results in:
 
     <my-tag><h1>hello</h1></my-tag>
 
-In 3.0, `can.mustache` syntax (requiring `@`) will change to `can.stache`'s' (not requiring `@`).
+In 3.0, `can.mustache` syntax (requiring `"@"`) will change to `can.stache`'s (not requiring `"@"`).
 
 If the tag's `title` attribute is changed, it updates the scope property 
 automatically.  This can be seen in the following example:
 
 @demo can/component/examples/accordion.html
 
-Clicking the __Change title__ button sets a `<panel>` element's "title" attribute like:
+Clicking the __Change title__ button sets a `<panel>` element's `title` attribute like:
 
     $("#out").on("click", "button", function(){
       $("panel:first").attr("title", "Users")

contributing.md

@@ -213,6 +213,32 @@ For long comments, use:
     /* myFn
      * Four score and seven—pause—minutes ago...
      */
+
+### Documentation
+
+The documentation for the different modules should be clear and consistent. Explanations should be concise, and examples of code should be included where appropriate. In terms of format and style, here are a few suggestions to keep the documentation consistent within a module and across all parts of CanJS:
+
+#### When referencing another part of CanJS, make sure to link the first reference in a section.
+
+For instance, when documenting `can.Component.scope`, the first reference to `can.Component`, `can.route`, or any other part of CanJS should be enclosed in square brackets, so that links to those docs are generated. Linking each occurrence isn't necessary, but all the other references should at least be surrounded by "grave accents" or tickmarks.
+
+	This is an example of linking to [can.Component] from another page. If you reference
+	`can.Component` later in this section, you don't have to link to it. All subsequent
+	references to `can.Component` have grave accents or tickmarks surrounding them.
+
+	### New Section
+
+	Another section referencing [can.Component] starts this trend again...
+
+**Note**: The one exception to this is on the module page. When documenting `can.Component` itself, only use the tickmarks, as linking to `can.Component` would just link to the page you are currently modifying.
+
+#### Enclose string literals in tickmarks as they should appear in code
+
+If the developer should type `"@"`, use the tickmarks to make this clear. This avoids the ambiguity of whether the apostrophes or quote marks are part of the text that should be typed. This also applies to any references to variable/key names (e.g., `scope` versus "scope" or **scope**).
+
+#### Include a clear description of your example code
+
+For a developer that's new to CanJS, the description of the example is likely more important than the example itself. Make sure there is a clear description of what the code should accomplish. This includes using all the techniques above. A good description should answer the question, "could you explain what this example code is doing?"
 
 ## List of heroes