2008Q4 Grant Proposal: Moose Docs
Sun, 02-Nov-2008 by
Alberto Simões
edit post
<![CDATA[
* **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.
**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::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.
**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.
]]>
Comments (16)
This grant looks to me like an answer to my blogpost ( http://nxadm.wordpress.com/2008/07/12/object-oriented-perl/ ) concerning Object Oriented perl. :)
Specially compare to java, OO perl is a lot of work (often not very intuitive). Moose could be a solution.
However, the Moose documentation is really lacking. I hope this grant will get accepted.
http://nxadm.wordpress.com/2008/07/12/object-oriented-perl/
I believe Dave is a good choice for this, and that it's a great proposal. Moose is a phenomenal tool, and with better documentation will be much more widely used and usable.
YES!
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.
I'd like to see this grant happen.
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.
- Stevan
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.
- Stevan
+1
Agreed. Dave's documentation work is good and this is an essential for Moose I think.
As someone who would like to learn Moose (aka: a noob), I would definitely like to see this get approval.
KennV
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 is an excellent proposal. Dave Rolsky is a good documentor and an excellent programmer and I think he would be ideal for this.
As for the idea itself, Moose is a fantastic OO system which lacks a really comprehensive documentation package. This will be a real asset to Perl 5 development.
I wholeheartedly 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.
I have read David's Moose::Unsweetened, it is an excellent little gem, and can only say I fully support this grant and wish him Godspeed!
