2008Q4 Grant Proposal: Moose Docs

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.

Author
Dave Rolsky

Title
Moose (and Class::MOP) Documentation Improvements

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

Write a set of Moose::Intro::* docs

Revise all of the existing cookbook recipes

Write the recipes marked as TODO

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

Amount Requested
$3,000

That's a lot of money, but writing all this documentation will be a lot of work. While many people are willing to write code, fewer are willing to write docs, and even fewer are good at it. I'm both willing and good at it.

The one thing that I miss in Moose docs is how to use Moose with existing class hierarchies mentioning all the common solutions and gotchas. This might be trivial - but as a beginner I can attest that this is the biggest conceptual barrier.

For example, to understand how to use "delegate" (in fact, Moose doesn't have such a keyword, and it's "handles", as is an option of "has", that Moose uses for "delegate".), I couldn't the detailed explanation about "handles" anywhere. So I had no choice but to read at least two sources, 010_attribute_delegation.t and 011_more_attr_delegation.t. It's like putting the cart before the horse.
In summary, I don't doubt that this project has worth getting grant.

Good proposal and I echo rjbs's thought that Dave is a good choice for this. I've already enjoyed his blog entries (http://blog.urth.org/2008/09/new-moose-docs-aim-to-answer-what-is-moose-and-why-moose.html) on his work for moose docs so this would just be a natural extension of that.

As the writer of a good portion of the original Moose docs (yes, you can blame me), I think this is a really good idea and Dave is the *perfect* person for the job. Not only does he understand the Moose guts extremely well (he has been responsible for the last several releases and many excellent core improvements), but he is also an accomplished writer and a MUCH better speller then I will ever be.

As the writer of a good portion of the original Moose docs (yes, you can blame me), I think this is a really good idea and Dave is the *perfect* person for the job. Not only does he understand the Moose guts extremely well (he has been responsible for the last several releases and many excellent core improvements), but he is also an accomplished writer and a MUCH better speller then I will ever be.

I'm the author of the Moose Quick Ref Card. I wrote that to help myself when I was learning Moose, because the docs are not well organized and do need some beginner-facing TLC. Dave would be an excellent choice for this, and this is such a well used module system that there will be widespread benefit. I support this proposal.

Yes! This should be the preferred way to do objects in Perl. It needs documentation so that newbies can get up to speed. Documentation for projects with legs like Moose and Mojo are only good things for the Perl community.