2008Q3 Grant Proposal: Module Installation Configuration Wizard

8 Comments
  • Author: Michael G Schwern
  • Title: Module Authoring Documentation
  • Synopsis: Write documentation targeted specifically at Perl module authors using both Module::Build and MakeMaker. This includes basic authoring tutorials, information about XS and a cookbook for advanced issues. Specifically separate the documentation to address the different concerns. Also complete the author API documentation of both Module::Build and MakeMaker. Separate basic and advanced API information (for example, INSTALL_BASE and SIGN are basic but POLLUTE and PERLMAINCC are advanced) for easier reading.

Author
Michael G Schwern

Title
Module Authoring Documentation

Synopsis
Write documentation targeted specifically at Perl module authors using both Module::Build and MakeMaker. This includes basic authoring tutorials, information about XS and a cookbook for advanced issues. Specifically separate the documentation to address the different concerns.

Also complete the author API documentation of both Module::Build and MakeMaker. Separate basic and advanced API information (for example, INSTALL_BASE and SIGN are basic but POLLUTE and PERLMAINCC are advanced) for easier reading.

Benefits to the Perl Community:
Information about how to author a module is scattered across many documents. Much of it is incomplete or written for the wrong audience in far too much technical detail. Basic information is often hidden in piles of advanced detail. Most documentation is centered around documenting the details of the API rather than focused on what the author wants to do. Finally, what author-centric documentation is out there is often out of date or advocating cargo-culted information.

The current lack of information makes module authoring look far more complex than it is resulting in programmers being frightened of releasing their code. Documentation centered on what the author wants to get done will make writing Perl modules easier and encourage more code to be released.

Accurate and up-to-date documentation written by authoring experts will make Perl modules better by allowing users to avoid out of date or subtly incorrect techniques.

Deliverables
For both MakeMaker and Module::Build...

  • Basic
  • File layout (lib/ t/ bin/ ...)
  • Magic variables ($VERSION, @ISA)
  • Where do tests go?
  • ...
  • XS
  • Simple
  • Complicated
  • Wrapping an existing library
  • ...
  • Specific issues / FAQ / Cookbook
  • Dealing with configuration data
  • MakeMaker, Module::Build, Module::Install: Which to use?
  • Overriding existing functionality
  • Adding new targets
  • Installing programs
  • Modifying the source on the fly
  • Customizing testing behavior
  • ...
  • API

Project Details
The main goal of the project is not complete documentation coverage but to write enough of the documentation so that others feel comfortable filling in the gaps.

Some incomplete attempts at this sort of thing have been tried in the past, Extutils::MakeMaker::Tutorial, Module::Build::Authoring, Module::Build::API and Module::Build::Cookbook for example.

The Module::Build documentation will be significantly easier, especially the advanced topics, as Module::Build is simply easier to extend and better documented. Many of the issues have no good answer for MakeMaker.

Project Schedule:
There's a solid two months of writing and getting feedback from module authors here.

The project will be greatly accelerated by the availability of the SVN aware podwiki proposed elsewhere. It will allow easier and earlier collaboration by wider audience.

Biography
Michael Schwern maintains ExtUtils::MakeMaker and has worked extensively on Module::Build. He works on usability issues in Perl.

Amount Requested:
$6000

8 Comments

I think this is the best idea ever.

This sounds like a very useful and important proposal to me.

This sounds like a very useful and important proposal to me.

It's always seemed to me that there were methods that most module authors used to standardize their module creation that were hard to determine. Making those methods transparent to new users (like myself) would be most excellent.

Sounds sensible, it's always good to have better documentation.

Excellent idea! Much needed.

I hope this will be done anyway ...
Or get a grant another time.

The title of the proposal and the body are mis-matched. The body is actually the "Module Authoring Documentation" proposal. I think I made that mistake in my original submission and it got copied.

The "Module Installation Wizard" proposal is here:
http://news.perlfoundation.org/2008/05/2008q2_grant_proposal_module_i.html

Not that I mind having either funded, though I should finish off my other projects first.

About TPF

The Perl Foundation - supporting the Perl community since 2000. Find out more at www.perlfoundation.org.

Recent Comments

  • schwern.myopenid.com: The title of the proposal and the body are mis-matched. read more
  • Arthur Wolf again: I hope this will be done anyway ... Or get read more
  • FAGZAL: Excellent idea! Much needed. read more
  • acme: Sounds sensible, it's always good to have better documentation. read more
  • mikebaas.org: It's always seemed to me that there were methods that read more
  • Leon Timmermans: This sounds like a very useful and important proposal to read more
  • Leon Timmermans: This sounds like a very useful and important proposal to read more
  • Arthur Wolf: I think this is the best idea ever. read more

About this Entry

This page contains a single entry by Alberto Simões published on August 1, 2008 12:00 PM.

2008Q3 Grant Proposal: Bavl was the previous entry in this blog.

2008Q3 Grant Proposal: Improve POE::Component::IRC is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

OpenID accepted here Learn more about OpenID
Powered by Movable Type 4.38