Lots of comments, wow! :) On Fri, Apr 8, 2016 at 12:54 AM, Warren Young <wyml@etr-usa.com> wrote:
On Apr 7, 2016, at 5:13 AM, Sawyer X <xsawyerx@gmail.com> wrote:
I rewrote the documentation
*Which* documentation?
Shortly replying to this entire paragraph: the documentation I'm replacing is the Manual. It wasn't deleted yet. It might be deleted in the same PR once we feel comfortable with it, or it might be kept until a later commit. Depending on whether the old Manual still has anything we want covered. A reference should still exist, possibly in the Manual, possibly outside of it. This is not what this is about.
One of the biggest problems I’ve had with Dancer’s docs from day 1 is the distinction between
https://metacpan.org/pod/Dancer2 https://metacpan.org/pod/distribution/Dancer2/lib/Dancer2/Cookbook.pod https://metacpan.org/pod/distribution/Dancer2/lib/Dancer2/Manual.pod https://metacpan.org/pod/distribution/Dancer2/lib/Dancer2/Tutorial.pod
Each part exists for a reason, but I agree they conflate and are confusing. * Dancer2.pm was the main hub which should also be a very very light introduction (if any) and instead redirect you to the Manual. * Dancer2::Manual was to be a proper manual explaining how to use Dancer2, as prose. It will be superseded by this new documentation. At the end of the Manual there is a short reference, and that should be kept (maybe there, maybe elsewhere). * Dancer2::Tutorial is supposed to be an example on how to write an application with Dancer2. Instead of explaining the structure (Manual) and available keywords (reference), it actually leads you step by step on an application. Many people prefer learning this way. We discussed separating this into a class of sample applications. "Here's how to write X", "Here's how to write Y". * Dancer2::Cookbook contains interesting (and arguably useful) patterns users have. It literally started with people documenting practices they have which are supported but not keywords in and of themselves. ("Here's how you can define a default route", "Here's how you use the WRAPPER directive in TT"). Some of these should be removed because they are (or should be) covered in the Manual. Some really are things that are just good to write down somewhere because people try to do them (the TT one is a good example). I think we can all agree documentation is hard, but we need to start somewhere. Looking at the entire picture now and fixing it all at once (which is what I understand you're interested in) is not feasible. Many people tried, they all failed. I'm explicitly attempting to not do that.
and would be happy for comments.
perlcritic --brutal ? :)
Yes. But try to keep it practical. I want comments for the documentation that exists, not for the entire documentation in Dancer, all the available parts, reorganizing the entire thing, different available formats for documentation, etc. We're doing this step by step. This is not the last and only step, but it's a big one. If we draw back to "wait, let's go over *all* the documentation (including available documentation formats) and redo it", we won't actually move forward.
It's difficult to convey both how something works and how to use it.
That’s why I recommend two top-level documents: a user manual and a reference manual.
The reference manual exists to explain class interfaces and such. It is meant to be read at point-of-need, in any order. The existing POD docs do this adequately today.
The user manual is mainly prose, intended to be read in a specific order, up to the point that the reader loses interest. Thus, the easiest and most central topics come first, and later topics build on earlier material.
That's not a bad idea, however the Cookbook was deemed more than useful in many situations and many people prefer a tutorial when learning. In contrast, when asked about the docs, some people said, "You need a tutorial! More tutorials! Only tutorials!" - Different people, different thoughts on how to do it. Let's start with what we have in front of us.
The problem I identified above is largely because you’re trying to use POD — a tool intended more for reference docs — to generate a user manual.
For example, POD doesn’t let you have a “chapter 2” that follows “chapter 1” unless you do something ugly like:
Dancer2::UserMan::1_Introduction.pm Dancer2::UserMan::2_Tutorial.pm Dancer2::UserMan::3_...
That’s why we have Doxygen *and* Docbook, Epydoc *and* AsciiDoc, etc. Different tools for different purposes.
But assuming we're staying within the realm of Pod for now...
* Is this documentation too long?
Kind of.
You’re forced to put all of the material in a single POD because that’s the only way to get a strict ordering within POD, short of the naming hack I gave above.
Tools like Docbook and AsciiDoc have ways to define chapters which end up in separate HTML files, with hyperlinks chaining them in the correct order. Each file would have a name that describes the chapter, so you could predict its contents from its name.
Understood. But considering we're not moving to LaTeX... let's move on from this point.
* Is this documentation not enough?
I haven’t read it yet, but perhaps not.
The freedom to write arbitrary-length books in your user manual, chunked into reasonably-sized chapters, offers the freedom to write only as much as necessary, and no more.
When everything is in a single page, you start asking questions like this, wondering if you should write less text because it makes your single page too long.
I see you're very focused on this, but this is something we're not going to try and fix with this PR. So, please, let's move past this.