Dancer2

Dancer2 copied to clipboard

Docs are hard. We currently have the Introduction, the Tutorial, the Manual, and the Cookbook. It's hard to tell what is documented where.

The idea was that the Introduction explains things gently, the Tutorial walks you through writing an application, the Manual provides the complete coverage, and the Cookbook provides all the tips, tricks, and hints collected by developers (based heavily on contributor input).

I think the problem is mainly that we do not have a base-line for what skills you need in order to understand Dancer and how to use it. This means we have multiple places to start from, but they are not clear. Each one tries to cater to multiple different crowds.

What @mickeyn and I wanted to create was a simple guide that, assuming you know basic HTTP and Perl, explains the structure of the Dancer system: the Apps, the routing, the hooks, etc.

Starting from the ground up, this documentation is relatively thin but is able to not only cover a large and significant portion of the keywords, it also captures how Dancer works, and how its structured internally (to an extent).

@PerlDancer, any comments?

Not yet, will check in later!

excellent :+1:

@racke you promised to have a look at this...

Thanks for the reminder, @SysPete. Let's start with the simple things first - I found a small typo: https://github.com/racke/dancer2/commit/8c58764f62f601441c37263b09c3368968df58af.

Is there a way to get HTML out of the PODs with my old friend Dist::Zilla?

Simply using Pod::Simple::HTMLBatch won't work with the special POD elements.

@racke++ Thanks for the typo fix. I missed it.

Basically, dzil build and perldoc the POD. Wish it was easier, but it's not that bad, I guess.

The problem with perldoc is that it doesn't show any links etc.

get Handles GET methods.

I think this should say "Handles GET method" - we have only one.

It had a first glance at it before and will continue to review it. It is definitely well written and a big improvement for any user, especially new users.

What about adding some suggestions about common plugins? So many users try to reinvent the wheel for authentication, database access, you name it.

GET methods and GET method are both wrong, IMHO. What I should have written was handles requests using GET method.

Common plugins is a good idea, except the list of recommended modules would be limited. We can also half-endorse. Like, this exists.

Another note to self: would be great to have a synopsis including all the core pieces.

This documentation doesn't go into the details about the engines - which is fine, but we should add pointers from the Engine section so users can go into the details for loggers etc.

What details would you like it to go into?

Like an overview on the existing loggers and the configuration options.

It would probably be easier to merge this draft and add new issues for the stuff mentioned here :-).

Should we ask on the mailing list for people to review this?

What's hard for me is to answer the question: Is this better than what we had before? To me it feels like it because it's shorter, succinct, and (IMHO) teaches you more than the previous documentation - but I'm not sure what other people think.

On 03/08/2016 09:26 AM, Sawyer X wrote:

Should we ask on the mailing list for people to review this?

What's hard for me is to answer the question: Is this better than what we had before? To me it feels like it because it's shorter, succinct, and (IMHO) teaches you more than the previous documentation - but I'm not sure what other people think.

I'm quite convinced that this is better than before - and it can't hurt to give the people a chance to review it. I suggest to put in somewhere as HTML so people can browse it easily.

Regards Racke

Perl and Dancer Development

Maybe something along the lines of:

To convert a L<Dancer> application to L<Dancer2>, it may simply be a matter of changing use Dancer; to use Dancer2;. The +L<Dancer2::Manual::Migration> document covers any other changes you might...

I like that suggestion very much! I'll use that.

Updated.

What isn't discussed here yet is deprecating the existing Manual. This should effectively replace it. We would still keep the deployment doc, the migration doc, and an index of all the DSL. For now we can also keep the tutorial, although that can (and probably should) be split to another distribution.

What says @PerlDancer team?

I find the example code in the tutorial not very enticing, also it may lead people on the wrong path (code on their own instead using DBIC / DPAE). So I'm fine with removing that as well.

Otherwise I agree with the deprecation.

I agree with @racke.

Okay I want to push this forward. I realized we still have the old documentation in and I keep pointing to these commits as a more readable documentation. What is left on this to just merge it? (I rebased the branch.)

@xsawyerx I am really fond of this rewrite. I am a bit embarrassed to say that I haven't looked at them in a while though, and will take another read through once I finish this release this week. Then, let's please come up with a plan for merging and pushing these out, and deprecating the old Manual 💃 Will that work?

Here's an updated list of what this branch still needs to have in order to remove Dancer2::Manual:

• [ ] Document the rest of the hooks
• [ ] Document delayed responses
• [ ] File Handlers
• [ ] Moving the documentation on writing your own handler somewhere else?
• [ ] Error handling
• [ ] send_file
• [ ] Static file handling
• [ ] Uploading
• [ ] Configuration
• [ ] Logging
• [ ] Testing
• [ ] Packaging
• [ ] Middlewares
• [ ] Plugins
• [ ] DSL keywords
• [x] .dancer file

So, basically, this is tough. We can't merge this yet. I'm not sure one documentation is good for all of this. Perhaps it's time to break this up.

I'd be inclined to say that, if the merge conflicts can be fixed, this ought to be merged, and the doco as it then stands re-reviewed and improved further, using your checklist for inspiration. Even if it's not 100% complete, it looks to be a good improvement.

If I get a chance soon, I'd be happy to sit down and review the doco in detail and see what improvements I can come up with, too.

Right - this one needs addressing - good doco is incredibly important, and the great work done in this PR is sitting unused! I'm of the opinion that, even if there's some improvements still to be made, it's a good improvement, and so we should merge the bloody thing then improve iteratively, otherwise it'll never get in. Thoughts?

I only have two problems: 1. I don't want to merge this and to lose documentation for stuff I listed. 2. I want additional documentation to take the ideas I had in mind when writing this.

I can review this again over the weekend and try to add what's missing - at least the big stuff. What would be great is if it I can get around to write an internal documentation on how to document, like a style guide.

I can rebase this branch as well.