Merge branch 'docs/tprf-grant'

Author: cromedome

Changes

@@ -23,6 +23,8 @@
     [ DOCUMENTATION ]
     * GH #1342: Document skipping private methods in pod coverage tests
       (Jason A. Crome)
+    * PR #1721: New Dancer2 docs, reorganization of all documentation;
+      from TPRF grant (Jason A. Crome)
 
     [ DEPRECATED ]
     * None

README.md

@@ -36,50 +36,55 @@ Dancer2 is easy and fun:
 
 ## Documentation Index
 
-Documentation for Dancer2 is split into several sections:
+You have questions. We have answers.
 
 - Dancer2 Tutorial
 
-    If you've never danced before, you should start by reading
-    our [tutorial](https://metacpan.org/pod/Dancer2%3A%3ATutorial).
+    Want to learn by example? The [Dancer2 tutorial](https://metacpan.org/pod/Dancer2%3A%3ATutorial)
+    will take you from installation to a working application.
+
+- Quick Start
+
+    Want to get going faster? [Quick Start](https://somewhere) will help
+    you install Dancer2 and bootstrap a new application quickly.
 
 - Manual
 
-    The [Dancer2::Manual](https://metacpan.org/pod/Dancer2%3A%3AManual) is the definitive reference for Dancer2. Here you will find
-    information on the concepts of Dancer2 application development and a comprehensive reference to the Dancer2 domain specific
-    language.
+    Want to gain understanding of Dancer2 so you can use it best? The
+    [Dancer2::Manual](https://metacpan.org/pod/Dancer2%3A%3AManual) is a
+    comprehensive guide to the framework.
 
 - Keyword Guide
 
-    The complete list of keywords for Dancer2 is documented in the [DSL Keywords](https://metacpan.org/pod/Dancer2%3A%3AManual#DSL-KEYWORDS)
-    guide.
+    Looking for a list of all the keywords? The [DSL guide](https://metacpan.org/pod/Dancer2%3A%3AManual%3A%3AKeywords)
+    documents the entire Dancer2 DSL.
 
-- Deployment
+- Configuration
 
-    For configuration examples of different deployment solutions involving
-    Dancer2 and Plack, refer to [the deployment guide](https://metacpan.org/pod/Dancer2%3A%3AManual%3A%3ADeployment).
+    Need to fine tune your application? The [configuration guide](https://metacpan.org/pod/Dancer2%3A%3AConfig)
+    is a complete reference to all configuration options.
 
-- Cookbook
+- Deployment
 
-    Specific examples of code for real-life problems and some 'tricks' for
-    applications in Dancer2 can be found in [the Cookbook](https://metacpan.org/pod/Dancer2%3A%3ACookbook)
+    Ready to get your application off the ground? [Deploying Dancer2 Applications](https://metacpan.org/pod/Dancer2%3A%3AManual%3A%3ADeployment)
+    helps you deploy your application to a real-world host.
 
-- Configuration
+- Cookbook
 
-    For configuration file details refer to [Dancer2::Config](https://metacpan.org/pod/Dancer2%3A%3AConfig). It is a
-    complete list of all configuration options.
+    How do I...? Our [cookbook](https://metacpan.org/pod/Dancer2%3A%3ACookbook)
+    comes with various recipes in many tasty flavors!
 
 - Plugins
 
-    Refer to [Dancer2::Plugins](https://metacpan.org/pod/Dancer2%3A%3APlugins) for a curated list of Dancer2
-    plugins, or [search MetaCPAN](https://metacpan.org/search?q=Dancer2%3A%3APlugin) for a complete list.
+    Looking for add-on functionality for your application? The [plugin guide](https://metacpan.org/pod/Dancer2%3A%3APlugins)
+    contains our curated list of recommended plugins.
 
-    For information on how to author a plugin, see ["Writing the plugin" in Dancer2::Plugin](https://metacpan.org/pod/Dancer2%3A%3APlugin#Writing-the-plugin).
+    For information on how to author a plugin, see [the plugin author's guide](https://metacpan.org/pod/Dancer2%3A%3APlugin#Writing-the-plugin).
 
 - Dancer2 Migration Guide
 
-    [The migration guide](https://metacpan.org/pod/Dancer2%3A%3AManual%3A%3AMigration) provides the most up-to-date instructions on
-    how to convert a Dancer (1) based application to Dancer2.
+    Starting from Dancer 1? Jump over to [the migration guide](https://metacpan.org/pod/Dancer2%3A%3AManual%3A%3AMigration)
+    to learn how to make the smoothest transition to Dancer2.
 
 ### Other Documentation
 

lib/Dancer2.pm

@@ -123,72 +123,83 @@ __END__
 
 =head1 DESCRIPTION
 
-Dancer2 is the new generation of L<Dancer>, the lightweight web-framework for
+Dancer2 is the new generation of L<Dancer>, the lightweight web framework for
 Perl. Dancer2 is a complete rewrite based on L<Moo>.
 
 Dancer2 can optionally use XS modules for speed, but at its core remains
-fatpackable (packable by L<App::FatPacker>) so you could easily deploy Dancer2
+fatpackable (via L<App::FatPacker>), enabling you to easily deploy Dancer2
 applications on hosts that do not support custom CPAN modules.
 
-Dancer2 is easy and fun:
+Creating web applications with Dancer2 is easy and fun:
 
+    #!/usr/bin/env perl
+
+    package HelloWorld;
     use Dancer2;
-    get '/' => sub { "Hello World" };
-    dance;
+
+    get '/' => sub {
+        return "Hello, world!";
+    };
+
+    true;
+
+    HelloWorld->to_app;
 
 This is the main module for the Dancer2 distribution. It contains logic for
 creating a new Dancer2 application.
 
 =head2 Documentation Index
 
-Documentation on Dancer2 is split into several sections. Below is a
-complete outline on where to go for help.
+You have questions. We have answers.
 
 =over 4
 
 =item * Dancer2 Tutorial
 
-If you are new to the Dancer approach, you should start by reading
-our L<Dancer2::Tutorial>.
+Want to learn by example? The L<Dancer2::Manual::Tutorial> will take you from
+installation to a working application.
+
+item * Quick Start
+
+Want to get going faster? L<Quick Start|Dancer2::Manual::QuickStart> will help you install Dancer2
+and bootstrap a new application quickly.
 
 =item * Dancer2 Manual
 
-L<Dancer2::Manual> is the reference for Dancer2. Here you will find
-information on the concepts of Dancer2 application development and
-a comprehensive reference to the Dancer2 domain specific
-language.
+Want to gain understanding of Dancer2 so you can use it best? The
+L<Dancer2::Manual> is a comprehensive guide to the framework.
 
 =item * Dancer2 Keywords
 
-The keywords for Dancer2 can be found under L<DSL Keywords|Dancer2::Manual/DSL KEYWORDS>.
+Looking for list of all the keywords? The L<DSL guide|Dancer2::Manual::Keywords>
+documents the entire Dancer2 DSL.
 
-=item * Dancer2 Deployment
+=item * Dancer2 Config
 
-For configuration examples of different deployment solutions involving
-Dancer2 and Plack, refer to L<Dancer2::Manual::Deployment>.
+Need to fine tune your application? The L<configuration guide|Dancer2::Manual::Config>
+is the complete reference to all configuration options.
 
-=item * Dancer2 Cookbook
+=item * Dancer2 Deployment
 
-Specific examples of code for real-life problems and some 'tricks' for
-applications in Dancer can be found in L<Dancer2::Cookbook>
+Ready to get your application off the ground? L<Deploying Dancer2 applications|Dancer2::Manual::Deployment>
+helps you deploy your application to a real-world host.
 
-=item * Dancer2 Config
+=item * Dancer2 Cookbook
 
-For configuration file details refer to L<Dancer2::Config>. It is a
-complete list of all configuration options.
+How do I...? Our L<cookbook|Dancer2::Manual::Cookbook> comes with various recipes
+in many tasty flavors!
 
 =item * Dancer2 Plugins
 
-Refer to L<Dancer2::Plugins> for a partial list of available Dancer2
-plugins. Note that although we try to keep this list up to date we
-expect plugin authors to tell us about new modules.
+Looking for add-on functionality for your application? The L<plugin guide|Dancer2::Manual::Plugins>
+contains our curated list of recommended plugins.
 
-For information on how to author a plugin, see L<Dancer2::Plugin/Writing the plugin>.
+For information on how to author a plugin, see L<the plugin author's guide|Dancer2::Plugin/Writing the plugin>.
 
 =item * Dancer2 Migration guide
 
-L<Dancer2::Manual::Migration> provides the most up-to-date instruction on
-how to convert a Dancer (1) based application to Dancer2.
+Starting from Dancer 1? Jump over to the L<migration guide|Dancer2::Manual::Migration>
+to learn how to make the smoothest transition to Dancer2.
 
 =back
 
@@ -227,8 +238,9 @@ for guiding and shaping future development of Dancer2.
 =head1 SECURITY REPORTS
 
 If you need to report a security vulnerability in Dancer2, send all pertinent
-information to L<dancer-security@dancer.pm|mailto:dancer-security@dancer.pm>. These matters are taken
-extremely seriously, and will be addressed in the earliest timeframe possible.
+information to L<dancer-security@dancer.pm|mailto:dancer-security@dancer.pm>, or report it
+via the GitHub security tool. These reports will be addressed in the earliest possible
+timeframe.
 
 =head1 SUPPORT