Dave Rolsky - Moose docs

Title: Moose Docs

Name: Dave Rolsky

Grant Manager: Renée Bäecker

Duration: 3 to 4 months

Started: January, 2008

Amount Requested: $3000

Synopsis
This project will improve various aspects of the Moose documentation. The primary goal is to make Moose easier to understand for newcomers. The secondary goal is for Moose and Class::MOP to provide 100% complete API documentation for spelunkers.

Benefits
Moose is one of the most exciting projects to come out of the Perl community in several years. Like all (conceptually) big projects, it can be tough to get started. Making Moose easier to understand will benefit any programmer who wants to explore Moose.

There is also a broad benefit to the Perl community as a whole. Moose has the potential to be a "killer app" for Perl 5. However, Moose is a complicated and powerful system without enough documentation. More and better documentation will make it easier for people to learn how Moose can help them.

Moose provides a significantly more powerful OO mechanism than is natively available from Perl's primary scripting language competitors, PHP, Python, and Ruby. As such, I believe that Moose offers Perl 5 a real competitive advantage over such languages.

Deliverables

  1. Write a set of Moose::Intro::* docs
  2. Revise all of the existing cookbook recipes
  3. Write the recipes marked as TODO
  4. Complete API docs for all of Moose and Class::MOP

Description

The work for this grant will consist of writing new documentation as well as expanding and revising existing docs. It can be broken down into four chunks.

1. Write a set of Moose::Intro::* documentation. This would be a major expansion of the documentation currently in Moose::Intro. These docs will explain concepts in detail, and also explain why and when someone would choose to use a particular feature.

This differs from the cookbook, which is primarily aimed at showing examples of features in code, and then walking through that code.

The intro docs would include the following:

  • Moose::Intro::Attributes - what are attributes and how are they used? This piece of documentation would show all the different features available for attributes, including the "initializer", "clearer", "predicate", triggers, etc. It's likely that this will end up being split into two or three separate documents, since Moose has quite a lot of attribute-related features. For example, delegation could easily be in its own document, and it may make sense to split features into a "basic" and "advanced" set.
  • Moose::Intro::Subclassing - subclassing the Moose way. Subclassing in Moose is very simple, but different from the "old school" Perl 5 way.
  • Moose::Intro::MethodModifiers - a detailed discussion of each type of method modifier with explanations of when each is appropriate.
  • Moose::Intro::MooseObject - details of how Moose::Object works and the features it provides for its subclasses. In particular, this documentation would focus on how to use the BUILD, BUILDARGS, and DEMOLISH methods.
  • Moose::Intro::Roles - an explanation of what roles are and discussion of when to use them. This document would discuss how to apply multiple roles to classes, how to apply roles to other roles, and also how to apply roles to an instantiated object.
  • Moose::Intro::Types - an explanation of Moose's type system. This will include information on how and when to create your own types, and how to use coercion.
  • Moose::Intro::Introspection - what are metaclasses, meta-attributes, etc? This document will explain what the metaclasses are, and talk about how they can be used for introspection.
  • Moose::Intro::MooseX - an overview of some useful MooseX modules, specifically MooseX::AttributeHelpers, MooseX::StrictConstructor, MooseX::Params::Validate, and MooseX::Types.

2. Revise all of the existing cookbook recipes for clarity and simplicity. I've already done this for a few recipes, but there are quite a few left to do.

3. Write the recipes marked as TODO:

  • Moose::Cookbook::Basics::Recipe8 - Managing complex relations with trigger
  • Moose::Cookbook::Basics::Recipe11 - BUILD and BUILDARGS
  • Moose::Cookbook::Roles::Recipe3 - Runtime Role Composition
  • Moose::Cookbook::Meta::Recipe6 - Hooking into the immutabilization system
  • Moose::Cookbook::Meta::Recipe7 - Custom meta-instances

4. Complete API docs for all Moose and Class::MOP classes. Many of these classes have POD which simply lists their methods, without any explanation of what these methods do.

Details
The deliverables explain the full scope of the proposed project.

Schedule
My rough estimate for this project puts it at 80-100 hours of work. Some of this will come after the initial release of a piece of documentation, as people give feedback on it.

I have a full-time job, so this will have to be done in my free time. At a guess, I'd say this whole project will take about 8-12 weeks of calendar time until completion. I can start pretty much as soon as the grant is approved.

Biography
I am a member of the core Moose development team, and I've done the last few releases of Moose and Class::MOP. I've written a significant amount of new Moose documentation, including cookbooks recipes, Moose::Intro, and Moose::Unsweetened. This project has the support of the other Moose core team members, including Stevan Little, the original creator of Moose.

I'm also the author of a number of other widely used CPAN modules, including DateTime, Log::Dispatch, Exception::Class, and Params::Validate.

As a writer, I've co-authored two books for O'Reilly, the Mason and RT books. I've also written several articles for perl.com and The Perl Journal.