2010Q3 Grant Proposal: Perlbal documentation
Sun, 01-Aug-2010 by
Alberto Simões
edit post
<![CDATA[
<h1>Perlbal documentation</h1>
<dl>
<dt><strong>Name:</strong></dt>
<dd>
<p>José Castro
Bruno Martins</p>
</dd>
<dt><strong>Email:</strong></dt>
<dd>
<p>[hidden email]
[hidden email]</p>
</dd>
<dt><strong>Amount Requested:</strong></dt>
<dd>
<p>USD $ 2.500 (half for each of us)</p>
</dd>
</dl>
<p>
</p>
<h2>Synopsis</h2>
<p>Perlbal!</p>
<p>"It processes hundreds of millions of requests a day just for LiveJournal, Vox and TypePad and dozens of other "Web 2.0" applications."</p>
<p>It works great as a load balancer, wonderfully as a reverse proxy, marvellously as a web server.</p>
<p>If you know how to use it.</p>
<p>Perlbal lacks the documentation for even the simplest of tasks. Beginners can't possibly be expected to install and configure it by themselves, let alone write a plugin or accomplish some heavier task. At least not without losing some sanity.</p>
<p>However, all of these tasks are in fact easy ones.</p>
<p>But again, if you know how to do them.</p>
<p>This proposal aims at documenting several aspects of Perlbal and making several lives easier.</p>
<h2>Benefits to the Perl Community</h2>
<p>Grab a great Perl load balancing tool and make it usable to a broader audience.</p>
<p>
</p>
<h2>Deliverables</h2>
<p>Documentation detailing:</p>
<pre>
Installation
CookBook:
Using Perlbal as a reverse proxy
Using Perlbal as a load balancer
Using Perlbal as a web server
Managing and configuring Perlbal on-the-fly
Writing Plugins
Perlbal's Architecture at a glance</pre>
<p>The resulting document should make non-Perlbal users able to install, configure and even write a Perlbal plugin without having to read Perlbal's code and/or bang their heads against a desk in the middle of the night.</p>
<p>This documentation will be written in POD, so it can be distributed along with the code. This will also allow for a quick conversion to Wiki format, so that the project page on Google Code can show the documentation on the web.</p>
<p>
</p>
<h2>Project Details</h2>
<p>We already got in touch with Alan Kasindorf (Dormando), one of Perlbal's main developers/committers/release managers, who told us "That'd be great."</p>
<p>Alan pointed out the desire to write documentation for Perlbal and also the lack of time on his behalf.</p>
<p>We'll keep in touch with Alan to make sure the resulting documentation is in conformity to what would be expected.</p>
<p>
</p>
<h2>Inch-stones</h2>
<p>The project should take us 8 weeks, so we decided to detail some of the steps.</p>
<p>Also note that unless the Grant Committee advises us not to, we're keen on putting the documentation on a public github project from day one. It should also be noted that we intend on receiving the grant money even if other people start contributing to the project and aid us.</p>
<p>As soon as a chapter is completed, we can put it on Perlbal's homepage.</p>
<p>
</p>
<h3>Week 1 - Installation procedures</h3>
<p>We'll be installing Perlbal in a machine with barely anything on it (yes, we've done all these things before; several times).</p>
<p>We'll be documenting the process: all the steps, dependencies, requirements, problems we encounter and other possible problems we can think of.</p>
<p>This week should end with a document detailing everything a user needs to know to install Perlbal for the first time ever.</p>
<p>
</p>
<h3>Week 2 - Load Balancer</h3>
<p>Now we'll configure Perlbal as a Load Balancer.</p>
<p>Once again, we're going to be documenting all the steps taken.</p>
<p>The week should end with a document describing how Perlbal works as a Load Balancer, how to set it up, and containing examples for a few different setups.</p>
<p>
</p>
<h3>Weeks 3 and 4 - Reverse Proxy and Web Server</h3>
<p>More of the same.</p>
<p>More documentation, detailing all one needs to know to set up Perlbal as a Reverse Proxy or a Web Server, complete with a few recipes.</p>
<p>
</p>
<h3>Week 5 - Managing and configuring Perlbal on-the-fly</h3>
<p>During this week we'll be detailing how to check perlbal's status and how to configure it without restarting it.</p>
<p>
</p>
<h3>Week 6 - Plugins</h3>
<p>We'll be writing a couple of plugins.</p>
<p>The process will be documented and this should result in a document that will render any reader able to write their own plugin.</p>
<p>We'll also list the existing plugins out there, try some of them and describe how to use them.</p>
<p>
</p>
<h3>Week 7 - Bonus Week</h3>
<p>We'll be looking (once again) at Perlbal's architecture in order to detail it briefly to the curious user.</p>
<p>During this week we'll also be revising all the documentation written so far. That includes spell checking, grammar checking, content and recipes.</p>
<p>
</p>
<h2>Project Schedule</h2>
<p>Since our plan comprises 8 weeks, we're expecting it to take us 10.</p>
<p>It may look odd to an outsider, but we both have very demanding jobs where occasionally situations occur that require our attention after hours. That will leave us with very little time for this project and will end up delaying things.</p>
<p>It could also happen that we finish the project in 8 weeks, but our experience tells us we're better off with antecipating one rough week over the course of each month.</p>
<p>We'll still be aiming at the 8 weeks schedule, though, and doing our best to reach that target.</p>
<p>We can begin work on September 27th (this would make the end date December 6th).</p>
<p>
</p>
<h2>Completeness Criteria</h2>
<p>There will be documentation.</p>
<p>This should be readable, easy to understand, and contain instructions and examples on the following subjects:</p>
<pre>
Installation
CookBook:
Using Perlbal as a reverse proxy
Using Perlbal as a load balancer
Using Perlbal as a web server
Managing and configuring Perlbal on-the-fly
Writing Plugins
Perlbal's Architecture at a glance</pre>
<p>We understand how readibility and ease of understanding are very subjective concepts, but this is a documentation project, so we feel those should be the criteria.</p>
<p>We considered having the completeness of the project being evaluated by having the documentation figure on Perlbal's wiki or source code, but since we know that other people have their own lives too we'd prefer a) not to depend on anyone else to have the grant being considered successful and b) not to thrust that responsibility on someone who has no responsibility towards the grant.</p>
<p>
</p>
<h2>Bio</h2>
<p>We're two Perl developers based in Lisbon. We work at SAPO - Portugal's largest web portal - where we make use of Perlbal in several projects.</p>
<p>We've both used Perlbal and wrote plugins for it (Bruno has managed to release one of them to CPAN).</p>
<p>We both have code on CPAN:</p>
<pre>
<a href="http://search.cpan.org/~cog/">http://search.cpan.org/~cog/</a>
<a href="http://search.cpan.org/~bsm/">http://search.cpan.org/~bsm/</a></pre>
<p>We're both regulars at Perl events:</p>
<pre>
<a href="http://conferences.yapceurope.org/ye2010/user/154">http://conferences.yapceurope.org/ye2010/user/154</a>
<a href="http://conferences.yapceurope.org/ye2010/user/215">http://conferences.yapceurope.org/ye2010/user/215</a></pre>
<p>And, most important of all, we have both suffered at the hands of Perlbal, and wish no one else to have to suffer too.</p>
<p>
</p>
<h2>Links of interest</h2>
<pre>
Project homepage - <a href="http://www.danga.com/perlbal/">http://www.danga.com/perlbal/</a>
Source code - <a href="http://code.google.com/p/perlbal/">http://code.google.com/p/perlbal/</a>
Wikipedia page - <a href="http://en.wikipedia.org/wiki/Perlbal">http://en.wikipedia.org/wiki/Perlbal</a>
Perlbal stuff on CPAN - <a href="http://search.cpan.org/search?m=all&q=perlbal&s=1&n=50">http://search.cpan.org/search?m=all&q=perlbal&s=1&n=50</a></pre>
]]>
Comments (5)
More documentation/visibility for Perlbal would certainly be in line with the "promote successful Perl apps" meme.
I am not familiar with Perlbal, but I agree with pdonelan that promoting successful Perl apps is a good idea. The proposal is clearly written. I am unfamiliar with one of the proposers (B Martin) but know that the other proposer (J Castro) is a person who can be relied upon to get the job done.
As discussed on pm mailing list in the latest days, Perl is needing some good applications to promote the Perl language. I do not think we need new applications. Probably we just need to take some of these applications, like Perlbal, and make them fully documented. +1 for this grant.
Perlbal is an excellent piece of software. I don't see many people, that I'm sure would love it, actually use it because it lacks good documentation, examples of use and tutorials. I'm sure filling this void would benefit the project in particular, and also the entire community. It would also help to advertise excellent applications that are written in Perl.
Djabberd and qpsmtpd could use similar documentation work (and maybe some attention / code).
