Two Slashdot (and Slashcode) readers -- Alex McLintock of Openweb Analysts Ltd, and Dave Aiello of CTDATA -- have graciously contributed their impressions of the new O'Reilly book Running Weblogs With Slash. Since the Slash code is now used to run sites covering a huge number of topics (fly fishing, mountain biking, "news for nerds," etc.), it's time there was at least one printed reference to it.
I have been running two small-scale Slash sites since 1999. When I began developing web sites using Slash the only code available was Version 0.3, one of the first tarballs ever released by Rob Malda. That code was almost totally undocumented and not at all modular.
The Slash project has grown and the code has improved since then. Slash has now reached the point where it is a feature-laden, open source web publishing platform. However, documentation that can help new users has always been hard to come by.
I found a paragraph near the beginning of the book that I thought was important because it may help you to decide whether this book will be helpful to you:
The authors' choice of audience might also be why you have seen comments from some experienced Slash site maintainers indicating that they weren't entirely satisfied with the finished product. That's OK -- it wasn't written for them. But, if you have a desire to build a web site running on Slash and you don't want to spend the months that it took me to read the code line-by-line, "Running Weblogs with Slash" is a good place to start.This book is aimed at anyone interested in setting up and running a weblog with the Slash software. This includes system administrators and programmers, but attempts have been made to keep the discussion readable for people who have no desire to compile their own kernel or to rewrite the moderation system. It concentrates much more on how to accomplish things than how things work underneath, though it doesn't shy away from the greasy gears and wheels when appropriate.
The main part of the book begins with an overview chapter. It starts with a brief history of the Slash project. The next ten pages are a review of the user interface of Slashdot, including a number of screenshots. This is followed by three important short sections: The Slash Author Interface (administration), The Slash Publishing Cycle, and The Slash Architecture. These sections do not contain screenshots, but author interface is discussed in detail later in the book, and the publishing cycle and architecture parts have diagrams to help you visualize the concepts being discussed.
The next chapter, Installing Slash, may be the most important one of the book. This chapter is surprisingly short (about 21 pages) considering the difficulty that some people have installing the software. Two of the most critical pages of the chapter cover getting help with the key underlying software: mySQL, Perl, Apache, mod_perl, and Slash itself. All of the important URLs and mailing lists are documented here. A short outline of the installation process, and a set of step-by-step installation instructions follow. There are also short sections on building sites that are distributed across multiple machines, and running multiple virtual Slash sites on the same server.
Although the installation chapter is clearly written, some users may have difficulty completing it without a little frustration. For instance, the book says "Although many UNIX-like operating systems come with Perl already installed, building Apache with mod_perl requires the Perl source." It would help if the detailed installation section of the chapter indicated how to uninstall a binary version of Perl from at least one of the major Linux distributions. The authors have been consistent, however, in focusing this chapter on critical, Slash-specific installation issues.
The next five chapters of the book focus on Slash site administration. The topics covered include editing and updating stories, reviewing and approving submissions, comment-related functionality, moderation, and managing sections and topics. These chapters are important because most people who want to implement a Slash site have never seen the administration interface and need some help understanding the tools that are available. These chapters are also helpful to people who have experience with other web publishing systems, because a quick comparison can be done between the Slash author interface and the system with which the reader is more familiar.
The main part of the book concludes with chapters on managing a Slash-based community, basic and advanced customization, and advanced administration. The customization chapters are the only places in the main part of the book where the Perl code that makes up Slash is discussed in any detail. Now that Slash implements much of the web site's look and feel through the Template Toolkit, modification of the application source is much less important than it used to be. The advanced administration chapter is primarily about the Slash daemon (slashd), the tasks it performs (dailyStuff, moderatord, portald), and how tasks can be added and modified.
The appendices are easily the most technical part of the book. They begin with a detailed discussion of the Slash architecture, which includes several process diagrams, and a discussion of the Slash directory structure. The second appendix discusses the Slash database schema. The appendix on the Slash Template Language looks quite useful to people trying to modify the appearance of their Slash site. The Slash API appendix covers some of the important high-level functions that would be useful in building your own Slash plugin or theme. The last appendix covers Slash configuration variables, which can be important if you have to modify the location of Slash content in your file system, or you need to change other fundamental aspects of your site's configuration.
I would strongly recommend this book to you if you plan to build a Slash-based site and you want to develop a basic understanding of the Slash software as quickly as possible. You will also need to find resources (either in print or on-line) to help you understand administration of the underlying operating system, Perl, Apache, and mySQL, if you have little or no background in these subjects.
I'm sure that many people will be able to successfully install and operate Slash by using this book as their primary reference. And, if they have difficulty, they will have sufficient understanding of the architecture and terminology to ask "good questions" on the mailing lists or the Slashcode web site.
Alex McLintock's review:
This review basically lists the flaws and missing features in the book. But that doesn't mean it is a bad book - just that it is easier to find fault than praise. If you need a book on running a weblog with slash then buy this book.
About the Reviewer:
My slash experience is in running a book reviews website http://news.diversebooks.com/ using slashcode. I did set up a site years ago called "mines-a-pint.com" using a pre 1.0 version of slashcode but the site fell over due to lack of spare time.
I am also a perl programmer and web developer so I can figure out a huge variety of problems with Apache, mod_perl, and MySQL. This is lucky because slashcode depends quite greatly on the administrator having those skills. Sadly this book doesn't look into them in great detail. Were this a Wrox book the publishers would have copied a few chapters from different books - or at least given more details on how to troubleshoot those systems. The O'Reilly strategy is that you can perfectly well buy their book on MySQL, their Apache book, and their mod_perl book(s).
I was expecting more of a comparison of Slash to other weblogs. Why chose slash over others? It is in fact a hard question to answer unless you require a site really quite like http://slashdot.org The big benefit of being able to cope with a lot of traffic probably don't apply to most sites just starting out.
The book assumes you have greater than Slash 2.2.0, but presumably quite a few people such as myself have 2.0 installed and not upgraded yet. (I don't know how many people are running pre 1.0 slash sites). It doesn't mention how you upgrade. Lets face it - even if you installed the latest version today (2.2.5) you *will* have to upgrade at some point.
Setting Up Sites:
I expected this section to be a lot more detailed than the basic instructions - but it isn't so much better. When setting up slash sites there are at least three different types of user (slash, unix, and database) and these are not differentiated properly. The authors of the book fall too easily into using slashcode jargon without realising that someone coming to this for the first time wont know the slash-speak. I understand it because I've been reading the mailing list for nearly a year. However, someone picking up this book may not have.
Most jargon terms are introduced but they could be better explained - perhaps with more diagrams. As a typical example, it took me ages to understand the difference between topics and sections. It would have been great to see examples of how different slashcode sites decided what their topics and sections would be. Originally I just saw topics and sections as being a matrix of slots into which one would pigeonhole each article. However there are some things you can do with sections (the columns of the matrix) which you can't do with the topics (the rows). This seemed to me to be an arbitrary limitation of slashcode which an installer needs to be aware of when choosing topics and sections.
More screenshots of the default theme are needed. For instance it talks about the various slashboxes which are configurable but doesn't show them.
Virtual Slash Sites:
I pretended I was a newbie at this and tried to follow their instructions for installing virtual slash sites (ie multiple weblogs on the same machine). The instructions for setting up virtual users aren't complete. EG how do you *add* a new user to DBIx::Password I figured it out because I know perl but others may have significant problems....
Slightly Unusual Config:
I wanted to see if the book would tell me how to put all slash URLs inside a directory of a pre-existing site. (eg http://mysite.com/newsdir/slashpages ) but no found info on doing this at all....
This is a shame because it means that if you wish to combine slashcode with some other html you have to take the approach of installing slash and then adding the extra html content rather than the other way around. It should have considered the situation where someone already has a pre-existing website which they just want to enhance with some news capability.
Running a Slash Site:
There is not much description of the workflow of submitted articles through the system. Instead it is explained by describing what slashcode editors (aka "Authors") do. Looking at the article workflow is important because many other organisations will have different workflows and thus will need to change their behaviour to match Slashcode and not vice versa. This is generally a "bad thing".
Would I Buy This Book?
If I were installing slash for someone and I wasn't being paid to do all the maintenance I would have no hesitation in buying this book to help whoever is doing first line support. However I don't feel a desperate need to keep the book myself since I've already learned most of what it contains just by running a slash site. I know how to read the docs, look at the perl and database, and use the mailing list.
Ok - I can't do entirely without the book because it has some useful reference sections: a full third of the book is made from Appendices and index! One of the most useful of these is the chapter on Andy Wardley's Template Toolkit. I have a bit of an advantage here since I have used Andy's code before in a different web project. However most of my future slash site design will be done by a more junior web developer who doesn't have any perl experience and I expect this will be his most used chapter. (Check back to http://news.DiverseBooks.com in a few days for his additions to this review). The final appendix is useful too -- the list of configuration variables and their meanings.
You can purchase Running Weblogs with Slash from Fatbrain. Want to see your own review here? Just read the book review guidelines, then use Slashdot's handy submission form. (Psst! O'Reilly has also made available a 20% discount for Slashdot readers ordering by phone (800-294-4747), email (firstname.lastname@example.org) or from the O'Reilly web site. Use discount code "#E1EW36."