tobyink has asked for the wisdom of the Perl Monks concerning the following question:

I've been trying to update the docs for Type::Tiny and want feedback. Is there anything that's hard to understand, or needs explaining more?

In particular, it's Type::Tiny::Manual and the other pod pages in that namespace that I'm working on.

Replies are listed 'Best First'.
Re: Looking for feedback on my documentation
by 1nickt (Canon) on Nov 24, 2019 at 14:41 UTC

    Hi Toby, this seems like a lot of work, bravo! It's been some time since I had to refer to the doc, but it certainly seems to be many times more comprehensive. I didn't have time to read through all of it now, but I checked a few of the new POD pages and I like the clear, explanatory style filled with concise examples, per your usual. FWIW when I learned Type::Tiny I recall getting most of my info from your blogs, maybe Advent calendars, so it's nice to see it collected into the distro. Thanks for your contributions!


    The way forward always starts with a minimal test.
Re: Looking for feedback on my documentation
by Fletch (Bishop) on Nov 25, 2019 at 14:35 UTC

    In Type::Tiny::Manual::UsingWithMoo the second sentence after the first example codeblock for InstanceOf says "House" where it should be "Horse".

    So the horse's children should be an arrayref of other House objects.

    Update: that aside what I've read so far reads pretty well.

    The cake is a lie.
    The cake is a lie.
    The cake is a lie.

Re: Looking for feedback on my documentation
by NetWallah (Canon) on Nov 25, 2019 at 19:22 UTC
    Reading the Type::Tiny manual without a background in Antlers, rodent or bovine modules - it fails to convey the underlying purpose.

    A small code sample of usage without the animal references would certainly clarify that.

    Thanks for all your efforts!

                    "From there to here, from here to there, funny things are everywhere." -- Dr. Seuss

      Hmmm... were you reading Type::Tiny::Manual? Because I feel like your comment probably applies more to the Type::Tiny class documentation which is more internal and less good as a starting point. There is a pointer from Type::Tiny's pod to the manual, but it might need to be made more prominent.

        If you could throw in a statement from your blog article
        saying something like "Type::Tiny is a drop-in replacement for Params::Validate."

        That would help a lot.

        Even more helpful would be : synopsis -style code for : how to re-write your "sub hash_add()" parameter validator using Type::Tiny (without antlers/rodents etc).

                        "From there to here, from here to there, funny things are everywhere." -- Dr. Seuss