On Apr 8, 2016, at 1:39 AM, Sawyer X <[email protected]> wrote:
>
> On Fri, Apr 8, 2016 at 1:50 AM, Warren Young <[email protected]> wrote:
>> On Apr 7, 2016, at 5:13 AM, Sawyer X <[email protected]> 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.
_______________________________________________
dancer-users mailing list
[email protected]
http://lists.preshweb.co.uk/mailman/listinfo/dancer-users
