[dancer-users] [RFC] Rewritten documentation

[Sawyer X]

Lots of comments, wow! :)

On Fri, Apr 8, 2016 at 12:54 AM, Warren Young <wyml at etr-usa.com> wrote:
> On Apr 7, 2016, at 5:13 AM, Sawyer X <xsawyerx at 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.