[dancer-users] [RFC] Rewritten documentation

[Warren Young]

On Apr 7, 2016, at 5:13 AM, Sawyer X <xsawyerx at gmail.com> wrote:
> 
> I rewrote the documentation

*Which* documentation?

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

Ideally, all of this would be a single document, possibly in multiple chapters named after topics.

As it stands, I end up having to search all of them to find any given topic, because they’re all named generically.  

> and would be happy for comments.

perlcritic --brutal  ? :)

> 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.

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.

> * 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.

> * 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.

> * Does it explain things the documentation usually does not?
> * Do you think you understand more of how Dancer2 works now?
> * Does this clarify parts that were unclear before?
> * Any big pieces missing?

I wanted to get the above out before I read everything.  Expect at least one more reply.

> Thank you ever so much. :)

No, thank *you*. :)