[dancer-users] [RFC] Rewritten documentation

[Warren Young]

On Apr 8, 2016, at 1:39 AM, Sawyer X <xsawyerx at gmail.com> wrote:
> 
> 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
>> 
>> 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?

Because I have yet to come across a case where it matters.

In many apps, the code calling Dancer routes is either other Dancer routes (e.g. views which contain URLs pointing to other parts of the site) or JS code that calls back into the Dancer app, such as via Ajax.  In both of these broad cases, the caller and the callee are written by the same person, so you aren’t going to get a mismatch in intent.

If your app does allow outsiders to make calls into your Dancer app, such as via an API, what does it matter if the Dancer code says:

   post `/api/foo’ => {
       my $f = param ‘bar’;
   };

and the docs say you should call it as POST /api/foo?bar=x but the caller uses HTML form parameters instead?  The data was transferred and understood.

The only way I can see that it matters is if you write something like

   post `/api/foo/:bar’ => {
       my $f = param ‘bar’;
   };

and then the caller does something horrible like call POST /api/foo/x *and* pass a “bar” HTML form variable, leading to unclear intent.  But in that case, it is the caller that is confused, and the only problem is that the caller might not get the answer they expected.  But that’s the sort of thing you should expect when the API contract is violated, so why is it Dancer’s problem?

> Having handled parameters extensively, I have a
> strong understanding of the problems with "params”.

As I challenged you in the previous reply, provide a motivating example if you expect people to type ~3x as many characters on every parameter access.

Even if you come up with such a thing, I could only justify following that example in the few cases where I could see it was necessary a priori.  That is, call ‘param’ or ‘params’ most of the time, except in this one weird case where the distinction matters.

>> I think the material presently “Parameters” should be *last*,
> 
> 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.

That’s why I say “params” first, and “*_parameters” last.  You need to access your passed-in data early, but you don’t need to distinguish between the source of the data until much later, if ever.

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

Fine, but do you really need to get into architectural details in paragraph 12?

You don’t teach someone about functional programming by first teaching them the lambda calculus.  You don’t teach someone electronics by first deriving Maxwell’s equations from first principles.

(And yes, I’m aware that there are ivory tower pedagogues guilty of both crimes!)

>> Instead, I think you should go from “dancer2 -a Foo” to running it…
> 
> I can do this in person, I'm not sure how to do
> this in a manual.

Screenshots and console output.  PNGs and codeblocks.

> I can't imagine a manual saying "okay, now please
> change a few things, and try again". That won't work.

Works for me:

  http://tangentsoft.net/mysql++/doc/html/userman/tutorial.html

But part of that is because I’m using Docbook for that.

(Incidentally, I’m knocking down your “LaTeX” strawman from the previous reply here.   I never said “LaTeX”.)

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

The source code for that page of my MySQL++ manual is here:

  http://svn.gna.org/viewcvs/mysqlpp/trunk/doc/userman/tutorial.dbx?view=markup

I’m not advocating DocBook specifically.  I’m just pointing out that POD is scarcely more powerful than the “man” package for nroff, and it was intended for a different purpose.  If you want to write an article or book, there are more appropriate tools.

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

I’m saying that Starman and Memcached and Nginx and… don’t matter until months down the development pipeline, if at all.  But here you’re talking about them in paragraph N where N < 100.

If you’re still not convinced, explain to me how you program differently knowing that your session engine will be Dancer2::Session::Foo instead of Dancer2::Session::Simple?  That’s the whole point of abstraction layers: you can switch between them at will, for the most part.

That’s also why I talk about showing a switch of template engines early on: because although Dancer has a template engine abstraction layer, it is between Dancer core and the template engine, not between the template engine and the programmer.  Thus, the programmer needs to select their template engine early on.

This is not the case with session engines, caching systems, proxy layers, etc.

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

I mean you’re currently covering “var” between “forward” and “Hooks”, apparently because you want to group Vars with Cookies.  There’s nothing saying you must talk about Vars and Cookies at the same time, so why not move Vars until you’ve covered all of the keywords that require the use of Vars?

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

Yes, but is it common to need to know about it in the first 30 minutes of your Dancer training?

I think you might have lost perspective, coming from so many years of Dancer expertise.  You’re sitting there looking at what the app needs to look like 6 months down the line when it’s deployed and are trying to explain all the architectural details will be involved along the way, but your poor reader hasn’t seen Dancer before today, and is wondering how they can get Hello World talking to the Internet before lunch.