verb/docs/src/develop/guidelines.md

A project without documentation is like a project that doesn't exist. Verb solves this by making it dead simple to generate docs, using simple markdown templates, with zero configuration required.

# Verb Guidelines

> If you extend Verb or create a tool for the Verb community, please consider following these guidelines to provide the community with the most consistent experience possible. Thanks!

Of course, no one can tell you what to do with your own projects! So these guidelines are offered as a request, along with a hearty "thank you" if you decide to adhere to them.

## Describing Verb

Verb describes itself like this:

* _Verb makes it easy to build project documentation using simple markdown templates, with zero configuration required._

When describing Verb on another project, here is good format to follow:

* _[Your project description], [Verb description]_

For example, here is the description we use for Verb's [Yeoman generator](https://github.com/assemble/generator-verb):

> Kickstart the documentation for any project! This is the official Yeoman generator for Verb, a zero-configuration markdown documentation generator that is extremely easy to use and extend.

Broken down:

* Project description: _Kickstart the documentation for any project! This is the official Yeoman generator for Verb_
* Verb description: _a zero-configuration markdown documentation generator that is extremely easy to use and extend_


## Configuration vs. Conventions

Verb has a big heart, so it loves users and wants to be as configurable and flexible as possible. But Verb also has a big brain, so it knows that users won't know where to start unless well-defined conventions are established.

Best of all, **Verb knows how to compromise!**

Verb trieds to give users an easy way to get started, using hard-coded conventions that guide new users to a specific result. Verb doesn't bog newcomers down with lots of questions, or force users to make decisions before they see some kind of result.

### First Experience

Here is how Verb makes decisions, we suggest you do the same with your Verb-related projects (and probably other ones too!):

* Choose a specific "first experience" for your users.
* Make it basic, opinionated and approachable

_(TODO)_