2008Q3 Grant Proposal: Module Installation Configuration Wizard
Fri, 01-Aug-2008 by
Alberto Simões
edit post
<![CDATA[
* **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
]]>
Comments (8)
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.
