[dancer-users] [RFC] Rewritten documentation

[Sawyer X]

Hey fellow hackers!

TL;DR;

I rewrote the documentation and would be happy for comments. Following
is an explanation. If you're short on time, here's the PR link:

https://github.com/PerlDancer/Dancer2/pull/1069

It might be easier to view only the docs themselves, available here:

https://github.com/PerlDancer/Dancer2/blob/docs/from-scratch/lib/Dancer2.pm#L118

Long version:

Documentation is hard. You probably know this. It's difficult to
convey both how something works and how to use it. When working on a
framework, we often find ourselves explaining where it fits in and
how, and what is the problem the framework solves. In our context this
might explain the HTTP protocol, how to implement a web service, or
how to deploy an existing application or merge your new application
within existing code.

A while ago, following conversations on the topic, I decided to take a
stab at rewriting the entire documentation. My goals were simpe (and
daring):
* Explain what Dancer2 does
* Explain how Dancer2 is composed
* Explain how to set it up, configure it, and use it
* Cover all the important keywords

I had made the following assumptions:
* I focus on best practices
* I do not cover at length what I don't think should be done (call it
"bad practices")
* I provide follow-up links (or at least try) where I prefer not to go
into detail
* I do not explain how HTTP works or how web applications work

I would be grateful for any review of this work you can provide before
we merge it as the new official documentation. Here are some leading
questions to help you think through this:

* Is this documentation too long?
* Is this documentation not enough?
* Does it explain things the documentation usually does not?
* Do you think you understand more of how Dancer2 works now?
* Does this clarify parts that were unclear before?
* Any big pieces missing?

You can reply on the list or directly to me.

* The link to the Pull Request:

https://github.com/PerlDancer/Dancer2/pull/1069

* The link to the documentation directly:

https://github.com/PerlDancer/Dancer2/blob/docs/from-scratch/lib/Dancer2.pm#L118

Thank you ever so much. :)
Sawyer.