New documentation draft: #1069
New documentation draft: #1069
Conversation
|
@PerlDancer, any comments? |
|
Not yet, will check in later! |
|
excellent 👍 |
|
@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: racke@8c58764. 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, |
|
The problem with perldoc is that it doesn't show any links etc. |
|
get 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 |
|
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:
I'm quite convinced that this is better than before - and it can't hurt to give the people a chance to review it. Regards Perl and Dancer Development |
| generation of L<Dancer> and replaces L<Dancer>. | ||
|
|
||
| If you are converting a L<Dancer> application to L<Dancer2>, the | ||
| L<Dancer2::Manual::Migration> document covers the changes you might |
There was a problem hiding this comment.
"might" sounds a bit vague - consider deleting "might"
There was a problem hiding this comment.
I'm not sure every app actually needs updating. I don't want to make an assumption about it.
There was a problem hiding this comment.
On 04/07/2016 01:36 PM, Sawyer X wrote:
In lib/Dancer2.pm #1069 (comment):
=head1 DESCRIPTION
-Dancer2 is the new generation of L, the lightweight web-framework for
-Perl. Dancer2 is a complete rewrite based on L.
+Dancer2 is a lightweight micro web framework for Perl. It is the new
+generation of L and replaces L.
+
+If you are converting a L application to L, the
+LDancer2::Manual::Migration document covers the changes you mightI'm not sure every app actually needs updating. I don't want to make an assumption about it.
At the very least you need to replace Dancer with Dancer2 :-).
Regards
Racke
Perl and Dancer Development
There was a problem hiding this comment.
You're right. I'll make that correction.
|
Maybe something along the lines of: To convert a |
|
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. |
xsawyerx
force-pushed
the
docs/from-scratch
branch
from
222ea4c
to
ebaf242
Compare
|
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? |
|
@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? |
|
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. |
|
Please take a decision on this branch. Having it here so much time doesn't do any good. More like bad. Rebase it, and make your list of enhancements a list of issues, so people can pick low hanging fruit. |
|
I'd like to pitch and help where I can. I'm totally new to Dancer. However, this can be an asset as I can help point out what might be confusing to a newb. I'm a pretty decent writer. And I've never used GitHub and git on a serious project so it's a bit disorienting for me right now. So a little patience would be appreciated. Once I get my bearings, I should be able to help quite a bit. |
|
I agree with @ambs - anything we can do to get this going again and merged would be great. People have a love/hate relationship with the docs it seems, so doing something to make the docs even better would be a welcome improvement! |
|
Not having any direction, I went ahead and committed some changes last night to Manual.pod, mostly as an exercise for myself to help solidify what I already know about Dancer2 and just to help get a better overall feel for the current quality of the documentation as it currently stands. See #1424 for my pull request. Feel free to incorporate, or not, any of my changes as you see fit. Before I go too much further, though, I'd like to get a solid commitment that others are still interested in working collaboratively on this task which is now over 2 years old and doesn't show much signs of life. Can we set some kind of arbitrary deadline, like say, the end of January to have this effort wrapped up? And who, exactly, is still actively interested in working on this? Without knowing, I feel a bit left up in the air. |
cromedome
force-pushed
the
docs/from-scratch
branch
from
e89ee07
to
75db8f9
Compare
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).
I more strongly worded the section about the dance keyword in "Running the application" to further discourage people from using it. In the sessions section, I listed a couple of session engines that are suitable for production use to help address any questions about what is or isn't considered production ready.
This is a port of a commit by racke (GH #1329).
xsawyerx
force-pushed
the
docs/from-scratch
branch
from
75db8f9
to
615e61a
Compare
|
@cromedome and I discussed this work and we formed a plan for moving forward on it:
Additionally, we are thinking of cleaning up the documentation paths:
|
* Document all the different engines - what they do, why they exist * Document where plackup comes from * Fix wording on methods
* The .dancer file * Local configuration files * Defining routes returns a Dancer2::Core::Route object * The send_as keyword (along with content types) * Templates can be used anywhere * The request_data keyword
|
@racke not sure the fixes are good. Feel free to adjust. I couldn't come up with a better way to deal with some of them. |
lib/Dancer2.pm
Outdated
|
|
||
| This will match both F</view/> and F</new/view/here>. | ||
|
|
||
| Any capturing done in regular expressionos are available using the |
There was a problem hiding this comment.
s/expressionos/expressions/;
There was a problem hiding this comment.
I can't find this in the most recent version.
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).