[dancer-users] [RFC] Rewritten documentation

[Warren Young]

On Apr 7, 2016, at 5:13 AM, Sawyer X <xsawyerx at gmail.com> wrote:
> 
> * I focus on best practices
> * I do not cover at length what I don't think should be done (call it
> "bad practices”)

One example of this must be the insistence on ‘route_parameters’ and such.  I think it's a mistake not to use “params” almost completely through the tutorial.

Only once routes, sessions, etc. are all understood should you show an example of a case where you need to be specific about the kind of parameter you want.  *Then* introduce *_parameters().

If you can’t show such an example, don’t talk about the distinction at all.  You may come to believe, as I do, that the distinction doesn’t matter for a great many apps.

I’m glad that Dancer2 provides a way for me to be specific, but I’d rather not court RSI just to be needlessly precise.

I think the material presently “Parameters” should be *last*, being less important than Control Flow, Keeping Information, and Hooks.  (Yes, I mean take it out of “Handler”, and make it a peer to it.)  It should not have any “recap” because it should introduce the topic rather than recapitulate an earlier introduction.

It needs a motivating example at the end, to show an example of a case where using “params” gives the wrong result, so you need to use one of the *_parameters() keywords.

> * I provide follow-up links (or at least try) where I prefer not to go
> into detail

Yes, good, gooood.  Use the power of the dark s…um, HTML.

> * Does it explain things the documentation usually does not?

I think you get down into the details too early.  You jump from “dancer2 -a” to talking about engines, routes, and applications, then talk about how to write your own app without dancer2 -a.  That forces the reader to try to cram the D2 architecture into their head before they’ve even seen “hello world” run.

Instead, I think you should go from “dancer2 -a Foo” to running it.  Have the user modify a few things and see how that changes the running app.  That gives the user a chance to poke around in lib/Foo.pm.  Along the way, describe routes.

After that, have the user create an intentional error in lib/Foo.pm, observe the result in the browser, and then switch the environment to production — introducing the user to config.yml — to see how that changes the error as shown in the browser.

Then have them switch an engine, such as from Dancer2::Template::Simple to the full Template::Toolkit, and change something in the views file and the pm file that requires Template::Toolkit.

And only after all of that, talk about the concept of multiple apps.  Maybe have the user create lib/Bar.pm in a separate namespace, and show that the two apps are separate at runtime, not just on disk.

I realize that the notion of apps is a huge difference between D1 and D2, and that it is foremost in your mind as an architect of Dancer, but it is a fairly advanced concept that the user may not even have to deal with, at least at first.  If there were a Dancer book, I wouldn’t expect apps to appear until chapter 7 or so.

I wouldn’t talk about things like Starman at all.  Just point to the Deployment document and be done with it.  If you go with my userman idea and collect that document into the new one, it would be a fairly late chapter, near the end of the book.

Similarly, I think “Vars” probably shouldn’t be discussed until after both “forward” and Hooks.  Use those jumping mechanisms as a motivation for “var” and “vars”, which is indeed the reason for the keywords.

> * Do you think you understand more of how Dancer2 works now?

I think I’ve been using Dancer too long to be surprised by any of this. :)

> * Does this clarify parts that were unclear before?

I’m glad that you talk about ‘prefix’ earlier than in other Dancer docs I’ve read.  Only the most trivial Dancer app ends up with a flat route hierarchy, and thus has no use for ‘prefix’.

> * Any big pieces missing?

As I said in the previous email, I think several existing documents should merge into this, as separate chapters.  (And those possibly broken up into multiple chapters themselves.)

Once all of the primarily-prose information is organized that way, look through the outbound links to see if there is any other similar material that isn’t already linked to.  At minimum, there must be a bunch of Advent Calendar articles that are worth linking to.

This list should be carefully curated, not just a copy of the table of contents here:

  https://metacpan.org/release/Dancer2