[dancer-users] [RFC] Rewritten documentation

[Sawyer X]

On Fri, Apr 8, 2016 at 1:50 AM, Warren Young <wyml at etr-usa.com> wrote:
> 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.

Other than "I don't want extra typing of characters", can you explain
why it's a mistake? Having handled parameters extensively, I have a
strong understanding of the problems with "params". I would be happy
to understand why you're in favor of it, other than RSI.

>
> 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().

The goal was to introduce you from the top to using parameters based
on where they come from. Instead of saying "data!", we say "this
data!". This is on purpose. I presume that since you think "params()"
should be used instead in general, you probably don't see why I prefer
from the top to using specific 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 don't believe that. :)
(The greater the apps I worked on, the more I don't believe that.)

>
>
> 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.

So the options here are:
* Current: parameters, control flow, rest.
* Your #1 suggestion: control flow, keeping information, hooks, etc.
and then parameters.
* Your #2 suggestion: parameters a little, control flow, keeping
information, hooks, etc. parameters again.

Did I understand this correctly?

I would advise against parameters at the end because that's the first
thing people want to see. Explaining to someone "let me show you
control flows and hooks, we'll get to the core of what you're doing
later". The second suggestion is more plausible, but that would still
be splitting a concept which I think is simple and better to explain
all at once. I would be more than happy to see a suggestion on how you
would do it.

>
> 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 think you're missing the place I'm coming from then. You judge this
from the perspective of "I like params() and I want you to explain why
I shouldn't use it". I wanted to explicitly start from "here's how you
should do it". I don't want the documentation to be an argument or a
justification, it should be a documentation.

If you want, I have written about this here:
https://github.com/PerlDancer/Dancer2/pull/988
https://github.com/PerlDancer/Dancer2/pull/931
https://github.com/PerlDancer/Dancer2/pull/993

And the original article introducing our new approach:
http://bulknews.typepad.com/blog/2009/12/perl-why-parameters-sucks-and-what-we-can-do.html

Instead of arguing why one or the other should be used, I want to
focus on what should be used and not on what shouldn't be or on why.
That was one of the principles in writing this documentation.

>
>> * 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.

True. This was on purpose and perhaps one of the bigger things that
might need to be changed. Let me explain why I did it this way.

When running Dancer courses with Mickey Nasriachi (another core team
member), we found that much of the confusion people had with Dancer
was how it's structured and what things mean. When we said "a Dancer
App", people asked what that is. How is it different from a web app.
When we said "engine", people asked what those were and how that mixed
with the App. Eventually, it actually became easier to explain the
structure and then show how to use it. In practice, with groups, it
seemed like it helped grasp things easier because they fit into a
structure instead of general things like "routes" and "apps".

>
> 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.

That's not a bad idea. I can do this in person, I'm not sure how to do
this in a manual. I can't imagine a manual saying "okay, now please
change a few things, and try again". That won't work.

Can you formalize an example of how this would work in documentation?


>
> 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.

This was deemed to be working better from practicing it with groups.

>
> 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.

Interesting. Could you expand, please?

>
> 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.

Could you please expand?

>> * 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’.

And this is why I need to explain "appname" as well, because they are
both forms of expanding an application. This is why a Dancer App needs
to be explained earlier too, because then what does "appname" mean?
That's actually a very commonly used feature.

Thank you for all the feedback.
Sawyer.