2010Q3 Grant Proposal: Perlbal documentation

Perlbal documentation

Synopsis

"It processes hundreds of millions of requests a day just for LiveJournal, Vox and TypePad and dozens of other "Web 2.0" applications."

It works great as a load balancer, wonderfully as a reverse proxy, marvellously as a web server.

If you know how to use it.

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.

However, all of these tasks are in fact easy ones.

But again, if you know how to do them.

This proposal aims at documenting several aspects of Perlbal and making several lives easier.

Benefits to the Perl Community

Grab a great Perl load balancing tool and make it usable to a broader audience.

Deliverables

Documentation detailing:

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

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.

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.

Project Details

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

Alan pointed out the desire to write documentation for Perlbal and also the lack of time on his behalf.

We'll keep in touch with Alan to make sure the resulting documentation is in conformity to what would be expected.

Inch-stones

The project should take us 8 weeks, so we decided to detail some of the steps.

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.

As soon as a chapter is completed, we can put it on Perlbal's homepage.

Week 1 - Installation procedures

We'll be installing Perlbal in a machine with barely anything on it (yes, we've done all these things before; several times).

We'll be documenting the process: all the steps, dependencies, requirements, problems we encounter and other possible problems we can think of.

This week should end with a document detailing everything a user needs to know to install Perlbal for the first time ever.

Week 2 - Load Balancer

Now we'll configure Perlbal as a Load Balancer.

Once again, we're going to be documenting all the steps taken.

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.

Weeks 3 and 4 - Reverse Proxy and Web Server

More of the same.

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.

Week 5 - Managing and configuring Perlbal on-the-fly

During this week we'll be detailing how to check perlbal's status and how to configure it without restarting it.

Week 6 - Plugins

We'll be writing a couple of plugins.

The process will be documented and this should result in a document that will render any reader able to write their own plugin.

We'll also list the existing plugins out there, try some of them and describe how to use them.

Week 7 - Bonus Week

We'll be looking (once again) at Perlbal's architecture in order to detail it briefly to the curious user.

During this week we'll also be revising all the documentation written so far. That includes spell checking, grammar checking, content and recipes.

Project Schedule

Since our plan comprises 8 weeks, we're expecting it to take us 10.

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.

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.

We'll still be aiming at the 8 weeks schedule, though, and doing our best to reach that target.

We can begin work on September 27th (this would make the end date December 6th).

Completeness Criteria

There will be documentation.

This should be readable, easy to understand, and contain instructions and examples on the following subjects:

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

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.

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.

Bio

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.

We've both used Perlbal and wrote plugins for it (Bruno has managed to release one of them to CPAN).

Comments (5)

More documentation/visibility for Perlbal would certainly be in line with the "promote successful Perl apps" meme.

[ 841 ] |
Sun, 01-Aug-2010 by jamesekeenan

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.

[ 842 ] |
Sun, 01-Aug-2010 by albertosimões

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.

[ 843 ] |
Mon, 02-Aug-2010 by smash

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.

[ 844 ] |
Sat, 07-Aug-2010 by tehmoth

Djabberd and qpsmtpd could use similar documentation work (and maybe some attention / code).