Contributing page suggestion

[Leo2807]

I suggest creating some easy-to-acces contributor's starting guide page (for contribution to less, not to the docs) or something. It should just contain a little description of the source tree. Sometimes repo's with a lot of files can seem a bit daunting, especially if you don't know what their purpose is.

[matthew-dean]

Or (or in addition to) we start introducing more inline documentation.

[Leo2807]

A little documentation about the entry point and the steps required in the process would still be a nice addition. For example:

1. Load module foo
2. Execute function bar()
3. Parse result to JSON
4. Print JSON

[jonschlinkert]

:+1: yeah this is good. I recommend that we start using a docblock style of inline comments, like this

/**
 * ## .methodName(one, two, three)
 *
 * This is the description of the method.
 *
 * **Example:**
 *
 * ```js
 * methodName(a, b, c);
 * //=> 'foo'
 * ```
 * 
 * @method  methodName
 * @param  {String} `one` Brief description of one, if necessary
 * @param  {String} `two` Brief description of one, if necessary
 * @param  {String} `three` Brief description of one, if necessary
 * @return {String}
 * @api private
 */

fwiw, this isn't a "taste" thing, I personally don't like how these comments "look", but the advantages outweigh the appearance, since all of the source code documentation is easily parsed into markdown documentation. Not to mention it's really nice reading code that has descriptive comments like this, along with actual markdown-style usage examples embedded directly above the code.

Also, if you find this interesting I created a parser and really simple way of parsing/adding these comments to docs: https://github.com/jonschlinkert/verb-tag-jscomment.

Basically, all you do is add something like: {%= jscomments("lib/less/tree.js") %} to a markdown file where you want the docs to be output. Then run verb in the command line.

[jonschlinkert]

btw, initially this seemed like it would be time consuming, but on projects where I'm doing this we just started adding the comments incrementally, and it really has made maintenance a lot easier. just my 2c