Render documentation by default when using bump

[alexgig]

Unless it is configured otherwise, have Grove render documentation by default. This minimizes the need for configuration and gives the user the best experience right out of the box.

[cscalfani]

I thought about doing this but after surveying our 20 to 30 repos, I realized that documentation would be generated on far fewer than half of them, hence the default.

I didn't want a bunch of repos with empty elm-docs directories.

If you don't like this for your situation, you can configure Grove globally to generate documents by default and then turn them off explicitly on a case by case basis.

[alexgig]

Ya I have it globally configured to create documentation.

It seems our case would be a good one for using the --local --docs=off option instead of having that be the default.

In the general case, developers will use the Elm documentation format since the compiler requires placeholders at least. Since those will be there by default, it makes sense to render them by default.

I'm sure now that we have this tool, moving forward documenting in the code will be our default. Long term I think it makes sense.

[cscalfani]

Having function specific documentation is helpful for libraries. But as things get more complicated, API documentation is less and less useful. A great example can be seen at nodegit.

At first the documentation seems really nice. But it's just API docs. And when I starting using this library in Grove I found it sorely lacking.

What I needed for this library was how to use these functions together to accomplish larger goals. The example code they provided and their own source code was more useful to me than these extensive function by function docs.

Once I had that as a resource, I nearly stopped looking at the API docs.

This is why I don't plan to automatically create docs for elm-slate (when I finally get around to documenting it). It's just too complicated to expect that API docs are going to be useful. I expect that the documentation will consist of conceptual documentation, examples and most important, a few reference implementations.