H3RALD - Tag 'writing' (RSS Feed)

Introducing Glyph

h3rald@h3rald.com — Fri, 09 Apr 2010 17:30:39 -0000

I’ve been writing technical documents for a living for the past four years, and I can tell you: there is no easy way to go about it.

For example, you can use:

a Word Processor like MS Word, for example — anyone can do that, right? Sure, but no, thanks: I strongly believe that Word Processors should not be used for writing technical documents as I firmly don’t believe GUIs are suitable for doing this at a professional level.
a Document Authoring Software like Adobe Framemaker, Robohelp, etc. Still GUIs, only more complicated to use.
XML, like DITA or DocBook, or other markups, like ReStructuredText. Better, but still not easily extensible and flexible enough.
your company’s tools, if you have them. That’s great if they are usable enough and the result makes your boss happy.
LaTeX, and that’s probably your best option, if you know what you’re doing.
XHTML and CSS3, in conjunction with a PDF renderer like Prince XML — that’s great if you know HTML and CSS, and you don’t mind hand-crafting the structure of the document.

Lightweight markups

I love Textile and Markdown. When people aren’t looking, I even use them at work to generate HTML code, because it’s just so much faster. Textile in particular can be used as a drop-in replacement for HTML (and a bit of LaTeX, too), as it can produce most inline HTML tags effortlessly and some block-level tags, too.

For things like <div> tags and <tables> though, Textile is not the best thing in the world, so you normally end up falling back to HTML.

Another “problem” is that Textile or other similar lightweight markups cannot be extended easily, simply because they were not meant to be extended in the first place.

Moreover, if you are producing a book, Textile can’t help you if you want to generate things like a Table of Contents automatically or validate links: those things are simply not part of Textile’s job.

How Glyph can help

There are a few projects on the Internet that tackle structured document generation. One of them is Kitabu, which looks promising and is able to produce pretty documents using Textile and Prince for PDF rendering… but again, it’s not extensible because it relies too much on Textile and Markdown.

Glyph is different. For one, it is much younger than any other, therefore it is most likely full of bugs.

Jokes aside, Glyph follows a much more radical approach, which consists in using a macro language on top of Textile or Markdown. The good thing about it is that this macro language is very simple to learn and — most importantly — very easy to extend.

Here’s an example:

section[header[Something about Glyph]
You can use Glyph macros in conjunction
 with _Textile_ or _Markdown_ to
produce HTML files effortlessly.
  section[header[What about PDFs?|pdf]
Once you have a single, well-formatted HTML 
file, converting it to PDF is
extremely easy with a 3rd-party 
renderer like =>[http://www.princexml.com|Prince].
  ]   
]

Which translates to:

&lt;div class="section"&gt;
  &lt;h2 id="h_1"&gt;Something about Glyph&lt;/h2&gt;
  &lt;p&gt;You can use Glyph macros in conjunction with 
     &lt;em&gt;Textile&lt;/em&gt; or &lt;em&gt;Markdown&lt;/em&gt; to
     produce HTML files effortlessly.&lt;/p&gt;
  &lt;div class="section"&gt;
   &lt;h3 id="pdf"&gt;What about PDFs?&lt;/h3&gt;
   &lt;p&gt;Once you have a single, well-formatted HTML 
      file, converting it to PDF is
      extremely easy with a 3rd-party renderer 
      like &lt;a href="http://www.princexml.com"&gt;Prince&lt;/a&gt;.&lt;/p&gt;
  &lt;/div&gt;
&lt;/div&gt;

Glyph macros can be used to:

Generate block-level HTML tags not commonly managed by lightweight markups, like head, body, div and table.
Create and validate internal and external links.
Include and validate images and figures.
Automatically determine header levels based on the document structure.
Automatically generate a Table of Contents based on the document structure.
Store common snippets of text in a single YAML file and use them anywhere in your document, as many times as you need.
Store configuration settings in a YAML file and use them anywhere in your document, as many times as you need.
Evaluate Ruby code within your document.
Call macros from other macros (including snippets), carefully avoiding mutual calls.
Include text files in other text files.
Include the contents of configuration settings (author, title) in the document.
Filter input explicitly or implicitly, based on file extensions when including files.
Manage comments and todo items.

An example Glyph project? Sure, Glyph’s own guide (source — PDF output).

Technical Details

Glyph is built on top of the following Ruby Gems:

gli — For the high-level command line interface.
rake — For the mid-level interdependent task layer.
treetop — For parsing Glyph Language, whose grammar is ridiculously simple, but it seems to work so far.
extlib — Because I can’t leave without it.

Disclaimer

Glyph is alpha software (hence the 0.1.0 version number) — handle with care and be aware that everything could change tomorrow. If you want to keep up-to-date and/or provide feedback, feel free to join Glyph’s User Group.

For more information…

…head over to Glyph’s homepage.

Take back your site, with nanoc!

h3rald@h3rald.com — Tue, 15 Sep 2009 11:32:51 -0000

Back in 2004, when I bought the h3rald.com domain, this site was static. At the time I hardly knew HTML and CSS, nevermind server-side languages, so I remember creating a pseudo-template for the web site layout and using it whenever I wanted to create a new page, to preserve the overall look-and-feel. This was a crude and inefficient strategy, of course: whenever I changed the layout I had to replicate the change in all the pages of the site – the whole eight of them.

Five years later, after rebuilding this web site seven times using different backends (PHP + CakePHP, Ruby + Rails + Typo, etc.), I decided to make it static again, this time with a twist. It all started when I read a post by Tom Preston-Warner (GitHub co-founder) that I finally decided to give it a try. Today, the 8th release of this web site is 100% static: if you load any page, there’s no server-side interpretation going on, you’re just browsing a plain HTML page, at most with a few AJAX calls. But let’s start from the beginning…

Why I don’t need a blog platform

There’s nothing inherently wrong with blog platforms like Wordpress: they allow anyone to publish content on the web using a user-friendly administration area. They were built with one thing in mind: make publishing content on the web something as simple as possible, even for people who don’t know anything about HTML, let alone server-side scripting.

What about people who do know about web development though? Do they still need a blog platform? Depends. If you are comfortable with editing files using a text editor, if you enjoy using the command-line on a daily basis, if you like programming and hacking a little bit, if you don’t really care about fancy and user-friendly administration backends… then you probably don’t.

All you need is a system to transform a bunch of source files into a web site. The good news is that such system exists – and you’re also spoiled for choices!

Introducing site compilers

The first site compiler I discovered was Webby:

[…] Webby works by combining the contents of a page with a layout to produce HTML. The layout contains everything common to all the pages — HTML headers, navigation menu, footer, etc. — and the page contains just the information for that page. You can use your favorite markup language to write your pages; Webby supports quite a few.

There are quite a few applications like Webby, such as:

There are probably even more, with different features, but they all try to solve the same problem: provide a way to generate static web sites in an automated way.

I spent some time reading about each one of them, evaluating the pros and cons and in the end I decided to go for nanoc, simply because it was the only one that seemed to fit all my needs.

A quick overview of nanoc

nanoc is a nifty tool written in Ruby suitable for […] building small to medium-sized websites. In other words, anything which doesn’t involve some fancy user interaction. For what concerns blogs, the only user interaction is comments – but that’s fine, because there’s more than one web service for that, such as Disqus or IntenseDebate.

Some details on the project

Compared to the alternatives, nanoc is one of the most mature and most maintained, having hit just a few weeks ago its 3.0 release. Its creator, Denis Defreyne, uses it for his own web site and is involved with the project on a daily basis, both coding and offering support to nanoc users like myself who regularly ask questions on the nanoc user group.

Denis also seems very concerned about keeping documentation up-to-date – something that really impressed me from a technical writer’s point of view. The tutorial he put together will get you started in no time, and the manual will explain everything else you may possibly want to know. When release 3.0 came out he even put together a migration guide. If this is still not enough and you don’t mind spending some time extending the system, nanoc’s RDoc documentation is very comprehensive compared to other Ruby projects.

Sites, Items and data sources

nanoc ships with a really neat command line tool that can do most of the work for you. Nanoc3 create_site h3rald will create a new web site in a folder called h3rald. The contents of this folder are laid out according to a particular logic (convention over configuration, remember?) So:

content – your articles, pages, stylesheets, images, …all the site content and assets.
layouts – the site layouts (and partial layouts)
lib – place your custom ruby code and vendor libraries here
output – your “compiled” site, ready to be deployed
config.yaml – your site’s configuration file. The only one (and it’s just a few lines)
Rakefile – place any custom Rake task here
Rules – defines the rules for compilation, layout and routing

Here’s the default config.yaml file:

---
data_sources: 
- items_root: /
  layouts_root: /
  type: filesystem_compact
  output_dir: output

A data source in nanoc defines where data is retrieved from to create the web site. By default, the filesystem_compact data source requires that you create two files in the /content folder for each article or page of your web page:

One containing the actual content of the page
Another for the page’s arbitrary metadata

By personal preference, I chose the filesystem_combined data source, which allows you to combine the content and the metadata of a page in a single file.

The source code for this very article, for example, starts like this:

-----
type: article
tags:
- website
- ruby
- programming
- writing
date: 2009-09-15 13:32:51.049000 +02:00
permalink: take-back-your-site-with-nanoc
title: "Take back your site, with nanoc!"
toc: true
-----
Back in 2004, when I bought the h3rald.com domain, this site was static. At the time I hardly 
knew HTML and CSS, nevermind server-side languages, so I remember creating a _pseudo-template_ for
 the web site layout and using it whenever I wanted to create a new page, to preserve the overall look-and-feel. 
This was a crude and inefficient strategy, of course: whenever I changed the layout I had to replicate the change
 in all the pages of the site &ndash; the whole eight of them.

At run time, the content goes through a Textile filter and the metadata is used in layouts, to generate tag links automatically, for example.

Layouts, filters, and helpers

Layouts in nanoc are similar to layouts and views in Rails, but much simpler. The same applies to helpers. Here’s a snippet from my default layout:

        <div id="container">
          <!-- CONTENT START -->
          <div id="content" class="clearfix<%= (@item[:permalink] == 'home') ? ' home' : ' standard' %>">
            <h2><%= @item[:title] %></h2>
            <%   case @item[:type]
                when 'article' then%>
                <div id="content-header">
                  <%= render 'article_meta', :article => @item %>
                </div>
              <% end %>
              <hr />
              <div id="content-body">
                <%= yield %>
              </div>
              <div id="content-footer">
                <div class="share">
                  <script type="text/javascript" src="http://w.sharethis.com/button/sharethis.js#publisher=6e34d60c-b14e-4c19-9b2f-7c35a9f0ab09&amp;type=website&amp;linkfg=%23a4282d"></script>
                  <% if @item[:feed] then %>
                  <a href="<% @item[:feed_url] || @item[:feed]+"rss/" %>" type="application/rss+xml" rel="alternate"><img src="/images/theme/feed-icon-14x14.png" alt="#"/>H3RALD - <%= @item[:feed_title]%></a>
                  <% end %>
                </div>
                <%= render 'article_buttons' if @item[:type] == 'article' %>
              </div>
            </div>

This source code snippet shows quite a few features of nanoc’s layouts:

You can access the metadata of the page which is being rendered using the @item, so @item[:title] returns the page’s title, for example.
Layouts can be nested, and behave like Rails’s partials. The render takes a string parameter (the name of the layout to render) and an optional hash parameter to pass variables to the layout.
The yield method is used to include the content of a page.
Layouts support any kind of filter, like ERB for example. Go crazy.

Helpers can be used in layouts to perform common tasks, like creating links, feeds, navigation elements and so on. Check the source code docs for more info, and of course feel free to create your own as you see fit.

Finally, filters are used to filter content markup. nanoc ships with almost everything you need, from Textile to Haml to RDoc, but nobody forbids you to create your own, and it’s dead easy.

Rules and tasks

While tasks (as in Rake tasks) do not constitute a huge part of nanoc (but as usual, you may need to create your own to perform custom operations), Rules became, as of version 3, one of the key concepts to grasp in order to make everything work. Rules are stored in the Rules file of your nanoc site, they can be used to:

Define routes, i.e. where pages are deployed in the output folder.
Define how pages are compiled, which filters to apply to a particular set of pages, which layouts to use, etc.
Define how layout are handled, which filters to apply to a particular layout, etc.

You can find more information in the manual, along with other important information, but for now, let’s say you should be familiar with most of nanoc’s jargon and how it works. Let’s see what you can do with it, in practice.

Migrating from your blog platform

As of version 7, h3rald.com has been powered by the Typo blog platform. If you are not familiar with it, let’s just say it’s a sort of Wordpress built on top of Rails: database backend, pretty admin front-end, tags, comments, and all sort of things a blog may need. While Typo is pleasant enough to use, it has all the inherent disadvantages of any other similar platform:

It relies on a database
It relies on server-side scripting to render pages
It uses a complex caching mechanism to produce, ultimately, semi-static pages
It may be subject to exploits, attacks, high server loads, and similar
You can’t really customize it beyond a certain point
You have to upgrade your backend frequently, and often is not as painless as you may expect
You can’t use versioning tools like git for your content, as it’s stored in a database

I’m not claiming that nanoc is blogging’s silver bullet (it was not created for that), but for sure:

It does not rely on a database
It does not rely on server-side scripting to render pages (not in real-time, anyway)
It does not need a complex caching mechanism simply because it produces static pages
It is definitely less prone to nasty things
It’s extremely flexible and hackable with very little effort
You don’t have to upgrade all the time, but it is really painless if you decide to
You can use git and similar: your content is in plain old text files

Rants are beside the point, suffice to say I recently convinced myself that switching from Typo to nanoc was a good thing, so let’s see how it worked out.

Posts, pages and comments

Out of Typo’s MySQL database, I just wanted to get the following data:

Pages and posts
Tags
Comments

Following the approach used by Jekyll, I decided to use the simple and powerful Sequel gem. I’m sorry to disappoint you, but the whole migration process can be summarize with the following Rake task:

  task :migrate, :db, :usr, :pwd, :host do |t, args|
    raise RuntimeError, "Please provide :db, :usr, :pass" unless args[:db] && args[:usr] && args[:pwd]
    db = Sequel.mysql args[:db], :user => args[:usr], :password => args[:pwd], :host => args[:host] || 'localhost'
    # Remove all existing pages!
    dir = Pathname.new(Dir.pwd/'content')
    dir.rmtree if dir.exist?
    dir.mkpath
    # Prepare page data
    dataset = db[:contents].where("state = 'published' || type = 'Page'")
    total = dataset.count 
    c = 1
    total_tags = []
    dataset.each do |a|
      puts "Migrating [#{c}/#{total}]: '#{a[:title]}'..."
      meta = {}
      meta['tags'] = get_tags a[:keywords]
      meta['comments'] = get_comments db, a[:id]
      meta['permalink'] = a[:permalink] || a[:name]
      meta['title'] = a[:title]
      meta['type'] = a[:type].downcase
      meta['date'] = a[:published_at]
      meta['toc'] = true
      meta['filters_pre'], extension = get_filter db, a[:text_filter_id]
      contents = convert_code_blocks meta, a[:body]+a[:extended].to_s
      write_page meta, contents, extension
      c = c+1
    end
  end

That’s it. Well, almost: you can find the get_comments, get_tags and get_filter methods in a separate utility file. Nothing special really, just a few convenience methods wrapping queries or simply processing data. Note how all information, including tags and legacy comments, is saved in each page’s metadata. The write_page method simply creates a file in the /contents folder.

Filters and highlighters

On my old site, I used mainly Textile and Markdown to write posts. However, some of my really old articles used BBCode, whose corresponding filter is not available in nanoc. No worries, I soon found out that creating a new nanoc filter came down to this:

require 'rubygems'
require 'bb-ruby'

class BbcodeFilter < Nanoc3::Filter
  identifier :bbcode

  def run(content, args)
    content.bbcode_to_html
  end

end

Yes, that’s it. Granted, the bb-ruby gem does all the work, but notice how easy it is to just plug in new Ruby code into nanoc’s architecture!

The next big challange was code highlighting. After a quick research, I found at least a half dozen of possible solutions to highlight source code. Some were javascript based, others were based on a server-side language like PHP, Ruby or Python. Again, I looked at Jekyll for inspiration and discovered they integrated the Pygments Python library. Why use a Python library for code highlighting in a Ruby-based project? Because there’s nothing to stop you (if you can run Python on your server, that is), because it looks very neat and because it supports a lot of different programming languages.

Lazy as I am, I more or less dropped Chris Wanstrath’s Ruby wrapper into my /lib folder (I just used Open3 instead of Open4 for Windows compatibility), and monkey-patched nanoc’s filtering helper as follows:

module Nanoc3::Helpers::Filtering

  def highlight(syntax, &block)
    # Seamlessly ripped off from the filter method...
    # Capture block
    data = capture(&block)
    # Reconvert 
    data.gsub! /<%/, ''
    # Filter captured data
    filtered_data = "\n<notextile>"+Albino.colorize(data, syntax)+"</notextile>\n" rescue data 
    # Append filtered data to buffer
    buffer = eval('_erbout', block.binding)
    buffer << filtered_data
  end

end

include Nanoc3::Helpers::Filtering

There you go, another thing sorted.

Tags and Feeds

Adding tagging support was a tiny bit more tricky. nanoc supports content tagging out-of-the-box though metadata and a simple helper, but I wanted to create tag pages (with feeds). Nothing too difficult though, it all came down to a simple Rake task:

  task :tags do
    site = Nanoc3::Site.new('.')
    site.load_data
    dir = Pathname(Dir.pwd)/'content/tags'
    dir.rmtree if dir.exist?
    dir.mkpath
    tags = {}
    # Collect tag and page data
    site.items.each do |p|
      next unless p.attributes[:tags]
      p.attributes[:tags].each do |t|
        if tags[t]
          tags[t] = tags[t]+1
        else
          tags[t] = 1 
        end
      end
    end
    # Write pages
    tags.each_pair do |k, v|
      write_tag_page dir, k, v
      write_tag_feed_page dir, k, 'RSS'
      write_tag_feed_page dir, k, 'Atom'
    end
  end

Again, you can find all the other simple utility methods in my utility file.

When it came to feeds, I decided to create a new method for the Blogging helper to create RSS feeds, although nanoc does come with an Atom feed generator:

  def rss_feed(params={})
    require 'builder'
    require 'time'
    prepare_feed params
    # Create builder
    buffer = ''
    xml = Builder::XmlMarkup.new(:target => buffer, :indent => 2)
    # Build feed
    xml.instruct!
    xml.rss(:version => '2.0') do
      xml.channel do
        xml.title @item[:title]
        xml.language 'en-us'
        xml.lastBuildDate @item[:last][:date].rfc822
        xml.ttl '40'
        xml.link @site.config[:base_url]
        xml.description
        @item[:articles].each do |a|
          xml.item do
            xml.title a[:title]
            xml.description @item[:content_proc].call(a)
            xml.pubDate a[:date].rfc822
            xml.guid url_for(a)
            xml.link url_for(a)
            xml.author @site.config[:author_email]
            xml.comments url_for(a)+'#comments'
            a[:tags].each do |t|
              xml.category t
            end
          end
        end
      end
      buffer
    end
  end

Nothing too daunting, once you get used to Ruby’s XML builder. I followed a similar approach for my monthly archives

3rd-party services

Finally, the interactive bits. I basically turned to third-party services and a bit of jQuery for everything which required user-interaction or pulling data from other web sites. Here’s a list of services and APIs I currently use:

IntenseDebate, for comments.
Google AJAX Search API for internal site-wide search.
Twitter JSON API to fetch tweets.
Delicious JSON API to fetch delicious bookmarks.
BackType JSON API to fetch comments from other sites.
GitHub JSON API to fetch GitHub commits for most of my projects

If you want to know how I integrated them, check out my /js folder, it was very simple, really.

Conclusion

I was very happy of switching to nanoc. It didn’t take me long, and I spent most of the time with non-nanoc issues (brushing up jQuery, CSS, graphics, etc.). Of course knowing the Ruby programming language helps, and if you’re not comfortable with hacking your way a little bit, then maybe it’s not for you.

Personally, I’ve been waiting for something like nanoc for a long time: its simple and yet powerful architecture makes you able to do virtually anything with it. For the first time in a long time, I feel like I’m in complete control of my web site, I know every bits of it and if I want to change the way it works or looks I only have to touch a few files.

nanoc’s metadata is mindblowing for its simplicity and power: although you’re not dealing with a database, you can query your content in the easiest ways possible. Whenever I needed a way to easily access pages, filter them, add extra logic to them, I just added metadata. If you forget something, you don’t have to change your database tables, create new relationships or anything of the sort, you simply add metadata to pages.

Be warned that tweaking nanoc gets addictive very quickly: you soon end up creating silly little tasks for making things just the way you want. For me, adding a new article to my blog now just means this:

$ rake site:article name=take-back-your-site-with-nanoc
$ vim content/articles/take-back-your-site-with-nanoc
... write & close the file ...
$ Nanoc3 compile

…Exactly what I need. Nothing more, nothing less.

Rails-powered Open Source Killer Apps, Anyone?

h3rald@h3rald.com — Sun, 02 Nov 2008 09:41:00 -0000

Lately I’ve been meandering around the web to find a good CMS for a family site I’d like to set up.
Why a CMS? Well, for a few simple reasons:

I don’t have enough free time to fiddle with Rails and make my own (I’m an Hobbyist Programmer™: I code for fun and enlightment, not for money)
Even if I had the time, I’m sure there are plenty of CMSes out there which suits my needs.

It turns out that reason #2 is not really applicable in this case, especially if we restrict the field to Ruby + Rails/Merb/<insert cool DRY framework here>.h3. Rails-powered CMSes

Name a Rails-powered CMS, quick!

Easy: Radiant.

Hmm, no. As much as I do like Radiant, it really cannot be considered a general-purpose CMS, can it? When it comes to build nearly-static sites in a clean and neat way I’d pick it any day, but it lacks quite a lot of community features like comments, ability to create forums, etc. etc. It does, however, support multilingual content in a rudimentary, yet effective way: create each translated page manually and use consistent URL conventions (/en/about, /it/about, etc.).

I’m not saying that there aren’t enough CMSes built on Rails, just that there’s no “killer app” in the pack. A “killer” CMS would be something as powerful as Drupal, but easier to use and more modular.

Here’s an incomplete list of the Rails CMSes I’m currently aware of:

Name	First Impressions/Comments
Radiant	Mature, suitable for administering static sites
Typo	Mature, one of the best blogging engines out there (my opinion is slightly biased though)
Mephisto	Mature, blogging engine
Rubricks	Under development, basic features if compared to other non-Rails solutions
Slate	Missing a lot of features if compared to competitors
Beast	Forum engine, extremely ligtweight
RailFrog	Not sure if it’s still being updated, not so many features
Zena	Alpha, looks promising although it doesn’t offer many features
simplelog	Yet another blogging engine. Simple and easy to use
oooopen rcms	Early development stage (dead?), minimal feature set
Geego	Multilingual, not so many out-of-the-box features

[Psst, if you know any other Rails CMS I missed out, mention it in a comment and I’ll update this table!]

Developing Proprietary Web Applications with Rails

What’s wrong with all of these? Normally one of three things: either they are mature, production-ready but focused on only one particular function (blog, forum, etc.), or they are still too new to be used seriously or they are slowly heading towards oblivion.

What’s going on here? Rails is a damn fine framework which offers all the modularity and power you need to build sites! Why isn’t there a fully fledged CMS to rival Drupal?
I think that part of the problem is that Rails is too good. Why build a CMS from scratch when you can develop a web site from scratch much more easily, tailored to your customer?

Rails has been used to build a few “mainstream” sites like Twitter (no bashing please!), Basecamp, GitHub and many more. What do these sites have in common? They are not open source. You cannot deploy your own Twitter on your server (You can with Laconica, though), you cannot deploy your own Basecamp to your server (you can with ProjectPier, an open source fork of ActiveCollab).

It feels like that even though Rails itself is open source, there aren’t that many open source Rails-powered projects after all. Maybe there are, but they do not really compare with similar alternatives offered in other languages. This is the reason why, despite its utter ugliness, PHP is still the Open Source King of the Web, and that’s very, very sad in my opinion.

Dreams on Rails

The annoying thing is that Rails is suitable to build CMSes, and good ones, too! Take Radiant and Typo, for example: they both excel in their own ways, in their own worlds.
Theorethically speaking, there’s no reason why someone couldn’t develop a modular system to glue different components together: you’d need common user administration and common workflow, a few hooks, and a solid set of conventions on how to build third-party components.
Hell guys, the folks at Drupal developed a huge (and successful) product with a million different ways to extend it in PHP. Even without using OOP! Every damn hook in the core is a function.

What does it take to do something like this using Rails, o Merb, or whatever else you like? You already have a very solid and consistent framework to build on (Rails), a way to automate tasks (Rake) and a language which lets you do everything you want, in a very elegant and organized way.

Rails lacks successful open source projects, in particular CMSes. I wish someone could fix this: not by coding the n^th^ CMS with the only two or three features you need, but by developing an high level application framework to build complex, dynamic and interactive web sites. Don’t even develop the whole damn thing: just come up with a set of conventions on how to extend a very basic core, and tell people how they can contribute, or even integrate existing applications into it.

The community will do the rest, hopefully… Or maybe are you too busy trying to roll out your newest, closed source startup?

If someone decides to develop such a powerful, high-level framework and is determined to keep it user-friendly and open source, I hereby promise to write the documentation for it, articles, and books. And I’m not kidding.

[UPDATED] A Glimpse of Hope

A few of the commenters of this article brought up a few interesting points and actually gave me a little bit of hope. Luigi Montanez pointed out that Rails was built to help developers build web sites. For now, Rails deployment isn’t as seamless as end users would like it, so there’s no point creating a killer app for such users if they can’t even get it to run on their $2/month shared hosting environment.
Nevertheless, there seems to be at least three different open source “social network engines” powered by Rails:

These are not CMSes in the early 2000’s sense, obviously, but they do provide the basis to effectively build a late Web 2.0-ish community web site. Each one of these project seems stable and mature enough to be used in production, but surely not as well-known as many other PHP-based solutions.

On the other hand, Priit Tamboom mentioned adva cms, a project still in alpha stage which aims to be more traditional and site-agnostic:

“[…] Different from other Rails applications the all-engines approach of adva cms allows you to build your own applications on top of it. It also makes it very flexible and extensible: our plan is to make it possible to only pick those engines/features that you really need for your application and omit the rest. As they are still all designed to work together seemlessly and reuse each others functionality the whole plattform feels much more consistent to a collection of similar but separate Rails applications. […]”

This sounds exactly like what I was hoping would come out from the Rails community: something in between a web development framework and an high-level CMS.
I’m definitely going to try it out (it’s an ideal weekend project) and I’ll report back once I know more about it.

Rails-Doc.org - A First Look

h3rald@h3rald.com — Thu, 19 Jun 2008 05:30:00 -0000

When you decided to learn Ruby on Rails (if you did, that is), chances are that you bought a book. I did, too, actually: there are a lot of very interesting and fairly comprehensive books out there after all.

I actually never bought a book to learn PHP, in the past though. Why’s that? Well, for two simple reasons:

The PHP manual can easily be searched and provides enough documentation, in most cases.
When the documentation is not enough, there’s always plenty of comments by experienced developers to save your day.

That being said, PHP is still an awfully disorganized language, but believe it or not, coming from PHP I didn’t find Rails documentation useful enough simply because it didn’t have these two simple but very powerful features.

Sure, there’s the Rails Documentation Project which provides more organized docs, and Noobkit does a nice job with its search-as-you-type feature… but still is not quite enough: you’d expect something much better than that for something like Rails!h3. Introducing Rails-Doc.org

Rails-Doc.org focuses on providing a better interface to Rails documentation by offering two key features:

A powerful, fast and useful document search
The possibility to add notes to Rails documentation

When the app went live, I immediately registered (it’s free of course) and started playing with it…

Search as you type…

The first thing I did was trying the search features, of course. I started typing “rout” for Routing, and I was immediately shown a list of matches:

It took a small fraction of a second to load the matches, which makes me think that definitely they have all the names indexed somewhere. Nevertheless, it was a pleasant surprise: normally, these search-as-you-type utilities are not that refined!

All you need to do is start typing at least three letters, and you get results, if any.
if you press ENTER, you get automatically redirected to the first result. This can be good, but maybe it would have been nicer to load a “traditional” list of results, but it depends on your taste, really.

…or browse through the namespaces

Alternatively, it is possible to browse the docs in the more traditional way, i.e. according to their class or module: the Browse page does just that: it lists all Rails classes and modules, regardless of the nesting. But there’s more: a little roundy icon precedes each class name, to indicate whether the documentation is present, and to what degree:

This is an interesting concept: in this way, in theory, people should contribute to the documentation where it’s more needed.

Each reference page is very neatly re-formatted: you can hardly imagine it’s actually the same content included in Rails’ RDoc pages!

Finally, another nice addition is the Related column, which lists links to other items which are related to the current topic:

Contribute, contribute, contribute!

You have to register for something, don’t you? Yes. If you register, you can post notes to any document. Simple enough, all you have to do is to click the Add Note button and a form will slide down for you to fill in:

As you start typing, you’ll notice that a preview of the note is displayed instantly: as you can use SimpleMarkup to write notes, exactly like in RDoc, this feature can be very handy:

What if there’s no documentation for a particular class or method? You’ll get a warning like this one:

The idea behind this is that, if you provide some useful insights, they’ll eventually end up in Rails core documentation.

An Short Interview with Mikael Roos, from Nodeta

Before the application went live, I was lucky enough to get Mikael Roos to answer to some of my questions. Here’s the full interview…

What are you actually trying to do on Rails-Doc.org?

The initial goal of the project is to provide the existing documentation in a more accessible way, most importantly to provide a lightning fast search feature that gives weighted results based on the
quality and amount of documentation. This we have already accomplished, and all remaining issues are related to browser compatibility. Another initial goal is to present a smooth interface for creating inline notes to
the documentation so that Rails developers can post notes about certain methods etc. for themselves and others to draw knowledge from.

Our longer-term goal (N.B. we are an agile project, so long-term means, say, three months) is to provide a way for the active members of the Rails community to improve the existing documentation based on the posted notes
to create an extended documentation that could optimally even be made in to a patch and would find its way back into the actual Rails source.

Another clear and obvious goal is to keep improving the service steadily as we progress toward the goals that I mentioned above.

Could you spend a few words on the “development process” followed by your company to develop this app? Did I read the word “Scrum” somewhere? Am I correct?

Yes, our development process of choice is Scrum. The core team is only three members, one backend developer, one backed/frontend develope and one frontend developer/UI specialist. I feel the team is optimal in many ways.
The team also has a few more experienced developers who are primarily active in other projects to ask questions from, one of whom is also the acting product owner on the Rails-doc project (that’s me!).

Did you develop it in three months, or…?

The first release was developed in three SPRINTS, not months – so what I’m saying is the first release was developed in five weeks (first sprint was mostly introductory and lasted a week, the next two sprints, first
development and then stabilization, were two weeks each). However, it is a FIRST RELEASE, which means the app is by all means not complete, but since we make software in a very agile way, it’a all about “Ship, ship, ship!”.

What is Nodeta, exactly? My Finnish is a bit rusty nowadays…

Nodeta is a software development company that focuses on web software. We employ a highly agile and effective process. We have worked both on light independent projects and in the environment of large global enterprises.
There are currently 10 Nodetans.

Rails-Doc.org is a pilot project for your new shiny app, ApiDock. Is it an open source app?

Unfortunately, I cannot go into details about APIdoc yet. What I can tell is that it is developed with Rails and that it won’t be open source, but rather it would optimally be offered as a service, which after all is what
the word “app” on the web means these days. Open source projects could however use it for free, sort of in the spirit of GitHub.

It will also most likely be separately targeted to larger companies.

Can you give me more technical details about the way keyword search is performed? Are you indexing/tagging documentation beforehand?

There will probably be a blog post on the Nodeta blog about the search and how it works after the first release comes out.

What about the social side of it: you’re hoping people will contribute with notes, which will then be collected and integrated in the documentation correct? Do you have any moderation or anti-spam precaution?

The quality of notes is judged in a social way. Notes can be thanked by other users and notes that get many thanks are showed in a more prominent way. Registration will be required in order to post notes and the registration will feature a captcha.

Will contributors be credited somehow? Who can contribute and at what level?

Anybody can post notes and good notes get thanks and thus so do their posters. Users that get lots of thanks will be later asked to become core users that can alter the extended documentation (not in the first
release.)

You want to blow out competition and that you don’t want to fail: sounds a good plan! How is Rails-Docs different from other similar apps?

We think that our app is the first that is serious about making things happen. We think about users first and above all at this stage our search feature is frankly unparallelled.

Do you have DHH’s seal of approval? Will you? Is there any copyright issue with your domain name?

Time will tell what DHH thinks. We did contact him just a few days ago to ask what his thoughts about all this are and are waiting for his comments. I doubt there is any wrinkles with copyright as Rails-doc itself is a completely non-profit project.

What about doing something similar for the whole Ruby language? Ruby docs may also be easier, in a way…

It is possible that we might do just that but right now it’s all about Rails.

The Bottom Line

Rails-Doc.org is definitely an interesting project, which has all the potential to become a powerful, Rails-powered service. Sure, it’s not open source and this can be a bit of a letdown for some: but after all people flocked to GitHub when it opened, didn’t they?

The search capabilities of Rails-Doc.org are definitely a very important step forward in making Rails documentation more accessible and easier to use, but the killer feature is definitely the possibility to add notes, if used wisely.

I’ll be watching this project closely and I’ll pay particular attention on what happens to the community’s contributions: will it really be useful? Will it really help creating documentation patches to Rails core? Only time will tell, of course.

Firefox 3 Revealed

h3rald@h3rald.com — Tue, 17 Jun 2008 02:46:00 -0000

When the SitePoint staff asked me to write an article summing up all the new features of Firefox 3, I gladly accepted: I wrote about Firefox before, and I thought it was just going to be a 2-3 hours job maximum.
After diving deeper into Firefox 3 development, reading dozens of different blogs and scouting Mozilla’s web sites, I realized I was wrong: Firefox 3 introduced a lot of new things, and keeping track of all of them, I admit, was quite a hard task.

Nevertheless, I wrote the article and delivered it to SitePoint in time fore the release, but my editor “complained” that 8,300+ words was about 3 times over the minimum requirements for a feature article!
“I don’t really think that people can read the whole thing online” —, he said, and I somehow agreed.

In the end, they decided to pack my “article” into a 30-pages PDF eBook which can be downloaded absolutely free of charge from SitePoint web site as well, so here it is:

Firefox 3 Revealed

If you prefer though, you can still read the article directly on SitePoint, here.

This guide aims to give you a comprehensive overview of virtually all the new features and improvements introduced by Firefox 3.

I would like to thank the whole SitePoint staff for giving me the opportunity to write this eBook, and in particular Matthew Magain for his help and support (and for creating the PDF on a Sunday evening!).
Additionally, I would also like to thank the Mozilla Development Team for their awesome job with Firefox 3 and everyone else who made this eBook possible.

Update: Feel free to digg this eBook!

10 reasons why I didn't update my blog

h3rald@h3rald.com — Thu, 12 Jun 2008 01:30:00 -0000

“It has been a while since my last post, sorry about that”
I read this sentence (or something along those lines) on many blogs on the Internet, including mine. As a matter of fact, I actually didn’t write a meaningful post on my blog for a long time and no, probably this is not going to change that either.

Yesterday I started thinking why this happens, not only to me but to a lot of other non-professional bloggers. A professional blogger &emdash; for what I can tell &emdash; is someone like Michael Arrington or Gina Trapani: someone who has the luck (or course) to be able to just blog for a living.

I don’t blog for a living: my site is self-sustaining via a few very unobtrusive ads, just that. I have a full time job, and I blog in my spare time about my interests, without even trying to make “proper” money from my site. There’s nothing wrong with it: I believe there are some other people in my condition, and that’s quite normal.

That being said, let’s examine the ten most common reasons why I (and you too, maybe) end up not updating my blog, even when I have time to do so.h3. Someone already blogged about it

This is very irritating. I am obsessed with original content. I want to write about something other people never (or hardly ever) wrote about. As a consequence, I often find myself googling the same topic I’m planning my blog post on, and I obviously often get quite a few results, too!

I actually wanted to title this very post “The Blogger’s Block”, but I immediately thought of putting that very title into Google, just to see if someone else already blogged about it. Sure they did! Not original at all, tough luck.
It also happened a few weeks ago: I wanted to write about the current state of tech news sites and Antonio Cangiano comes up with a similar post. Very interesting indeed, but quite annoying as well!

OK scrap that, think about something else…

This can potentially go on for days, and the only solution is of course trying not to worry about it, and just write the damn thing (that’s what I did to write this post).

I didn’t research enough on the subject

This happens tipically with reviews, round-ups, etc. Things I actually enjoy writing, but which may be easily subject to (harsh) criticism unless ou do them right.
I wanted to write a review of the new Treo 750 I bought. I’ve been using for a while, I learnt a few interesting hacks etc. etc. Unfortunately the 3G iPhone came out, so everyone is all hyped up about it. Too bad that I, being Italian and living in Italy, I never actually touched the damn thing!
What has that got to do with my Treo 750? Well, it would be nice to write a review of a Windows Mobile 6 phone comparing to the upcoming Apple wonder, wouldn’t it?

The solution to this would be trying to limit the scope of your post: screw Apple, let’s just focus on my Treo 750 and on the amazing amount of programming languages I can use on it!

After researching for X days, I realized it was all a waste of time

This happens with big articles. I once thought about writing a comprehensive article about all the possible ways to deploy a Ruby on Rails web site. Cool, isn’t it? I started researching about all the most esoteric lightweight web servers, about JRuby, Glassfish, IronRuby, … A lot of things. And new solutions kept coming up, and with them more and more posts, and then even entire books on the subjects.

Very frustrating. I abandoned the whole thing, because there was simply no reason to go on researching: it was all a waste of time.

How to fix this? Again, reduce the scope of your article so that you are able to reduce the time you spend researching about it. Or maybe try to get paid to write it, so that even if there’s plenty of articles about the same subject, at least you have a concrete purpose to write yours.

Erhm, yes, by the way, keep an eye on SitePoint in the next few days/weeks, OK?

I only write when I’m inspired, and now I’m not

Very, very common. I normally think about a very cool article to write in the evening, or early in the morning, or whenever I don’t have access to a computer or the Internet.
Of course I don’t forget about it, but by the time I have a chance to actually write it, I really don’t fancy doing so. Oh, the irony!
It happened today, actually, during my lunch break: I was supposed to write this post but I didn’t feel like it. I lost my inspiration and all my artistic verve, so no, it can’t be done. Tough luck, wait until next time.

How did I solve this? Well, I started writing the post in my coffee break: there was no way to finish it in time, of course, but at least I started it.
I also saved it to my PDA and continued writing it when I had a chance. Eventually, I managed to finish it during my lunch break, the next day.

Try to write whenever you are inspired. If you are not inspired in your lunch break, do some work in your lunch break and then write when, in an hour or so, probably, you feel like writing again.

This won’t make Digg’s front page

Digg, Reddit, DZone, you name it. They are all excellent free tools for promoting your content. Don’t tell me you never wrote a post for the sake of making the front page of one of those sites. I did, I confess.
I didn’t make Digg’s front page in a while, and I’m probably never going to make it again. The reason? When it comes to promoting the right content in a fair way Digg sucks. As a consequence, 80% of the articles which appear on Digg suck. I’m sure you’ll be able to forgive my French when I say that Digg utterly sucks.

No matter how clever your story may be, unless you’re backed up by a swarm or an active community willing to Digg your story, you simply aren’t going to make it. When is the last time a proper programming article made it to Digg? I don’t remember, probably way before I unsubscribed to the Digg’s Technology feed, about a year or so ago.

Just write for the sake of writing. Don’t even submit your story to Digg (unless you’re writing about the iPhone, of course, then you may have a chance): post it to a less-known site, maybe, or to Reddit, instead. You won’t get as much traffic, granted, but you also won’t get tons of idiots writing pointless crap on your site and you won’t risk a server crash. If it’s destiny, then some good soul will post it to Digg, but nobody will digg it. That’s just life, I’m afraid.

It has been too long since my last post: the next one will have to make up for it

This happens when you start feeling guilty because you didn’t post in a long time.

“My next post is going to be superb, long, interesting and everyone will start flocking back to my blog!”

Wrong. First of all because statistically people just don’t “flock back” because you bestowed them of one interesting post (you have to keep up, too), and second because by doing so your mind will automatically discard all those bits of things you wanted to write about, but you never did because you’re waiting for that special next post which will be so much better and will bring your blob back to ~~spam~~ life.

It happened, it happened… again, all you have to do is just post all the tidbits you need, while you’re preparing your big shot: your blog will remain “fresh” and more people will enjoy your interesting posts, whenever they’ll come.

Nobody gives a damn, anyway

I didn’t want to upset my younger audience by using a nasty f-word in the title, but that’s exactly how it feels like it, sometimes.
I went to Rome last week, did you know? I twittered about it, you ought to know! And of course you’ll all be waiting for the usual 10-page-long article on my awesome vacation. Like when I went to London, remember?
No, sadly not everyone may be interested in this crap. So I probably won’t post about it: who cares? When you start thinking like this, you may stop posting for weeks: not everyone may be interested in everything you post, and I believe that’s normal.
Especially for a blog like mine, which is deliberately open to all my interests: programming, technology, travelling, etc. That’s why most blogs try to be themed: they write about a particular subject, even a single programming project, and they (try to) do it well. The trade-off is that a themed blog may run out of posts amazingly quickly, if you’re not carefula and if you’re not 100% devoted to your blog’s theme.
A themed blog will build up a faithful audience, like when I was writing almost exclusively about CakePHP: a lot of PHP programmers where flocking here daily. Then things went wrong and I really couldn’t be bothered to write about the same crap. Which leads us to the next topic…

If I write about this, a large chunk of my audience is going to be upset

This applies especially to themed blogs: if you’re a well-known Firefox addict, you can’t suddenly start writing about Opera, praising its speed and the features it offers out-of-the box!
If you take a side, you’d better stick to it, if you want your audience to stick to you: the ten people who happen to read this blog are probably quite shocked by the amount of times I “changed side”: from CakePHP and PHP to Rails and Ruby, from Firefox to Opera (well, wait until my next SitePoint article comes out, at least…). Probably they are not the same people who read this blog a year or so ago.

In the end, it’s entirely up to you: if you are prone to radically change our opinion (and this happen in technology, much more than in politics), which involves changing the whole theme of your blog, maybe you should consider not having a themed blog at all.
And if you don’t feel 100% sure you want a themed blog, you definitely shouldn’t go for a themed domain name, or you may end up abandoning it afterwards. And when that happens, unless you’re writing damn cool posts like Why, it’s going to hurt your audience. On the other hand, if you’re sure you’ll get ten times more visitors, go for it.
No, h3rald.com stays… I may end up raving about Safari at some point within the next ten years though, don’t be upset!

I’m not an expert on the subject, so I shouldn’t blog about it

This is a common problem I have when I try to write about something I don’t know extensively enough. When I started to learn Ruby, I was eager to start writing about it: it seemed just too cool to be true!
I thought about writing a longish post on learning Ruby from scratch, but then I realized it wouldn’t have been a great idea: I was just starting to learn a new language, I didn’t know all the nitty-gritty and writing about it to teach others was going to be a bit presumptuous, maybe!
Instead, I opted for a lighted 10 reasons to learn Ruby article, clearly stating in the first paragraph that I was just a noob getting excited about his new toy. It worked, actually: people seemed to enjoy it, and I was partially excused for the few mistakes I made here and there.
You don’t have to be an expert to blog about something: you just have to be totally honest about what you know, and what you don’t know.

There are a lot of professional bloggers out there, and I’m not one of them

Finally, this can be summarized in two words: inferiority complex. “Proper” blogs fire out 10+ posts per day, and I don’t even write ten points in a month! Again, those a professional bloggers: they live for blogging (and make an awful lot of money out of it), and they most likely have someone else blogging for them, too!
Think of TechCrunch or LifeHacker, for example: they have a small legion of talented writers working for them &emdash; even if Michael Harrington does rant about Twitter about three times a week himself, though.
At the end of the day, what matters is the quality of your posts. Not the length minf, the Quality. I personally think that non-professionals (I said “non-professionals”, not “amateurs”!) are allowed to write about once a week, if they can provide good content, that is.

But you still do have to write at least once a week (OK, let’s make it ten days), otherwise either you’re justified (you genuinely don’t have time) or you may be a victim of one of these common fears. Watch out, and happy blogging!

Too many cooks... take #2

h3rald@h3rald.com — Sun, 02 Sep 2007 04:41:00 -0000

Today I was not going to post on my blog. I have the flu, I don’t feel very well so I started reading some news feeds on Google Reader. That lasted for about half an hour, so I decided to check my old Netvibes account where I kept other feeds, including a bunch of CakePHP-related blogs.

Two posts immediately grab my attention:

I don’t trust CakePHP or what should you say in public?

and

Bye, bye, CakePHP team

They’re both from Daniel’s cakebaker blog, the one I used to read when I was really into Cake.

To cut a long story short, apparently Daniel said something wrong and he got “what he deserves” for speaking out. Naughty boy!

That’s because it might have put “CakePHP and the team in a bad light”. Well, I don’t know about that, but definitely now it IS in a bad light!

I even found a bunch of comment which link this incident to what happened to me a few months ago:

“I said it when Fabio/H3rald left, and I’ll say it again—I think the biggest weakness of Cake is that the core dev team is quick to cut people out who don’t hold to every dogma the devs do. Fundamentalism, ego, call it what you will, a great community will only count for so long if the core keeps alienating its biggest allies. (not that they’re neccessarily alienating you, dho. I truly hope you stick around. You do seem to be taking it well.)”

^{^} Whoever you are, you’re 100% right.

A core asset (at least for his writings) of the CakePHP team is gone, and another (big) chunk of CakePHP PR strategy is out of play, now, it seems. While I’m sorry the CakePHP community has to get the butt-end of it as always, I’m certainly happy for Daniel who, like me, will now have a chance to look around and experiment with new things. That’s right man, Rails or Django are the way to go.

Back from holiday

h3rald@h3rald.com — Thu, 30 Aug 2007 02:59:00 -0000

I’m back. I was so eager to go on holiday that I didn’t even bother writing a post about it, too bad. I actually when on holiday for a week but I thought I’d take three weeks off from my blog duties in favor of laziness and relax, but unfortunately my laptop decided to go wrong as well, so I didn’t actually manage to relax that much.

Now everything is fine. I still have to send in my laptop for assistance but it’s usable at least, and I finally found the time (and the money) to buy a desktop PC. I always wanted to build my own, actually, but in the end I decided to opt for a pre-made Fujitsu Siemens, mainly for economic reasons and time constraints. I won’t publish the specs, but it’s alright for me and my fiancée.

So what now? Well… the usual: more posts will soon be added to the Simply On Rails series, a Ruby-related article is on the way (it will be edited by the excellent CyberArmy Publication Editing Staff this time), I may venture in a site upgrade whenever they decide to release version 4.2 of Typo which is supposed to be imminent and I’ll eventually complete another pet project of mine, but that will take more time…

Stay tuned.

Time for a diet...

h3rald@h3rald.com — Fri, 09 Mar 2007 10:59:00 -0000

My fiancée keeps telling me that too many cakes are not good for me, and I never listen: I always liked cakes! I did like the CakePHP™¹ framework too, once, and I did write some articles about it in the past, and I believe at least a bunch of Bakers found them useful, especially at the time.
I do believe the Cake™ Software Foundation¹ quite liked having their framework featured on popular websites like php|architect and SitePoint, and I believe that I contributed – to some extent – to make it one of the most popular frameworks available for the PHP programming language.

Unfortunately though someone decided that two of such articles and my personal website were no longer worth a mention on CakePHP official website frontpage. To me, this makes sense since the two CakePHP-related series which are being published by IBM are much more up-to-date than my articles, and thus deserve such a mention instead.

Oddly enough, I took a screenshot of the CakePHP website just yesterday “by chance” and my articles were still there:

…while this morning they weren’t anymore:

Of course I can’t provide any proof that I took the screenshot yesterday, and of course I don’t have any proof of the fact that someone in CSF may have thought that due to my recent bad behavior my articles didn’t deserve to be publicized anymore. I am confident that the Cake Software Foundation always does its best in keeping its site up-to-date, and I am glad that yesterday’s accident reminded them that there were far better articles which needed to be featured on their site. At least I finally did something good for the community!

Sarcasm apart, I feel I owe an apology for blowing this whole thing out of proportions: I disclosed embarassing details about our past project which – for the sake of the framework – should have never been made public, perhaps.
I want all of you to know that I still think that CakePHP is the best PHP framework ever made and I genuinely think that Larry E. Master did outstanding work in all this time, along with the rest of CSF members and contributors. Best of luck for your future editorial and development projects.

Since now my contributions are no longer “officially recognized”, I think I’d better to move on devoting my attention to something else.

¹ “CakePHP” and “Cake” seems to be registered trademarks of the Cake Software Foundation Inc. I’m not sure if I’m allowed to use them in this blog — If anyone has any problem with it, please let me know.

Too many cooks spoil the Cake book

h3rald@h3rald.com — Wed, 07 Mar 2007 01:45:00 -0000

I am sorry to announce that my upcoming book, CakePHP Recipes, will not be published anymore. As a matter of fact, it wasn’t finished because some of the people involved failed to comply with the terms of their contract in delivering material which was suitable for publication.

To quote an email I received from my publisher a few days ago,

“[…] The Cake Software Foundation has informed us they are withdrawing from the CakePHP Recipes project, and returning the advances they’ve received. This means we can no longer count on them for support, nor can we package the book as an official title.

After careful consideration, we have determined that this renders the book no longer viable for us. So, regrettably we must cancel your contract as well. Please understand that we have no quarrel with your performance; you have been responsive and communicative for the entire time. […]"

This is a huge disappointment to me, in particular because I am not responsible for the cancellation. It was going to be my very first book to be published, and due to someone else’s misjudgement and lack of motivation it will never be available to the readers.
I do not want to put the blame the whole Cake Software Foundation for this: nearly every person involved in the project did his best in reviewing parts of the book or offering me support. Regrettably this wasn’t enough: unfortunately it seems that someone didn’t like the idea of me writing the book and kept doubting not only my coding skills but also my ability as a writer all along.

It is sad to see how certain individuals fail to understand the importance of marketing and public relations not only when working on a team project but also in ordinary life, but it is truly disappointing to see how the thoughts and opinions of a single individual affect the work of a whole team.

Introducing: "CakePHP Recipes"

h3rald@h3rald.com — Thu, 02 Nov 2006 04:25:00 -0000

Despite all my efforts to keep the whole thing quiet for the time being, a few days ago I entered the words “CakePHP Recipes” in Google and discovered – to my astonishment – that my new book about the CakePHP framework is already for (pre)sale in many popular online bookstores.

Up to now I never made any formal announcement myself (although the Cake Software Foundation already did, months ago), nor gave out any juicy details about it, but maybe now the time has come to post something more about it. Yes, I am indeed writing a book about the CakePHP framework, and yes, you can already buy it but no, you can’t phisically get it simply because it’s still in progress (miracles of the modern publishing industry!).

I’d like to point out that I’m not the only author of the book: all the code examples and snippets included in the book is provided by the Cake Software Foundation staff, in the person of Larry E. Masters and Garrett J. Woodworth mainly, who will also act as technical editors and first reviewers of the book, together with other trusthworthy CakePHP core developers.
It is our intent to produce an enjoyable and yet very useful book which will hopefully help CakePHP enthusiasts to use the framework in real-world situations: the book will not focus on theory but on practice, by providing a lot of interesting “recipes” on how to implement a particular functionality in a CakePHP web application.

Why should you get it? Here are some reasons:

It is a book written by programmers for programmers
All the code included in the book has been created and tested by the creators of the framework
Part of all the revenues generated by the book (including royalties) will go to the Cake Software Foundation, and hopefully contribute to improve our already excellent framework.

Very special thanks to Peachpit Press for giving me and the Cake Software Foundation this chance to

More to come…

UPDATE: This book has been canceled and therefore will NEVER be available in bookshops or online stores.

Information Mapping

h3rald@h3rald.com — Fri, 02 Jun 2006 04:10:00 -0000

As I thought, my job also represents a great opportunity to learn new things. I don’t mean only new technical stuff, but also a great deal of tips, best practices and methods to efficiently write documentation material in proper English. Some theory about Information Mapping was by far the most interesting topic I learnt about this week.

What is Information Mapping?

Definition¹

The Information Mapping method is a research-based approach to the analysis, organization, and visual presentation of information.

Information Mapping is media independent

The method is both subject matter and media independent; that is, it can be applied to the subject matter of any industry, and it can be presented on paper, on a computer screen, verbally, or in a multimedia presentation.

Key Concepts

Information Mapping is an integrated set of easy-to-learn principles, techniques, and standards. It enables authors to break complex information into its most basic elements and then present those elements optimally for readers. The result is a set of precisely defined information modules that are consistent from author to author and document to document.

Purpose

The method helps writers analyze, organize, and present information with clarity focus and impact. Information That Works. The goal of the analysis component is to determine the

purpose

audience needs, and

information types.

The goal of the organization is to create an overall structure for the information, based on the results of your analysis. Finally, the goal of the presentation component is to format the information to make it clear and accessible to your audience.

¹ Contents were taken from InfoMap.com and were re-formatted and re-organized into an information map.

Key Concepts

Introduction

The Information Mapping method relies on some important principles according to which information should be organized. This method also defines new units of information to replace paragraphs, sections and chapters and tries to divide information into a few main set types, each with its own rules and structures.

Principles

Name Explanation

Chuncking Writers should group information into small, manageable units.

Relevance Writers should make sure that al information in a chunck relates to one main point (function or purpose).

Labeling Writers should provide a label for every unit of information.

Consistency Writers should use similar labels, word, formats for similar subject matters.

Integrated Graphics The use of tables, images, diagrams and lists is encouraged.

Accessible Detail Documents should provide sufficient details where necessary, to make the information more accessible for the readers.

Hierarchy Small, relevant units of information should be organized into a hierarchy.

Information Types

Name Definition

Procedure Set of steps to obtain a specified outcome

Process A series of changes through the time for some purpose

Structure Something which can be defined into multiple parts

Concept Group of physical objects, conditions, relations, …

Principle Statement of what should be done, assumptions

Fact Statement presented with no supporting evidence

Classification The sorting of a group of specimen into classes

Conclusion

Although it may initially seem too schematic, Information Mapping is a valid method to organize and present information to those readers who just need “facts” without any unnecessary distraction. This method it is used with some modifications in many technical manuals and documentation written by many companies.

Writing Tools

h3rald@h3rald.com — Thu, 25 May 2006 12:57:00 -0000

Since in these days (and even more in near future) I’m really writing a lot I thought it would be good to share my thoughts on some writing programs and tools I started using for writing these blog posts, articles, and more.

I’m going to examine a few applications which I find useful for different tasks, since I recently came to the conclusion that I cannot use the same editor for everything I write: some magazines require a .doc document, others want just plain text, my site uses the truly excellent textile markup, zZine Magazine used BBcode, other site use their own “proprietary” styles and so on. One could just give up and use Notepad – or better, Notepad++ – for everything, while someone else like me might opt for various applications according to the task.

One of the few essential requirements for a writer is some spell checking functionality. Sad but true, this is enough to leave the most popular multi-purpose programming editor out: programmers don’t need a spell checker, a highlighter for their favourite language is more than enough.
I will not mention all the applications I tried to find the Perfect Editor, and I’ll just focus on the programs I ended up using in the end. Some may be well known, others may not, anyway, here we go.

Word 2007 Beta 2 – Yes, I know that OpenOffice is free and OO Writer works great, but perhaps at work you’ll be asked to use MS Word. Some editors may require that as well, and their templates may not be correctly rendered by OpenOffice, so in the end you’ll still have to use Redmond’s most popular Word Processor – if you have it. If you got it with your laptop (I didn’t) or your auntie gave you 300$ to buy it you’re all set, but if you don’t?
Oh well, yes, OpenOffice is the right choice perhaps, but at least until February 2007 uncle Bill lets you try the bleeding (quite literally) edge of all the commercial word processors: Word 2007 beta 2. You can download the whole Office Suite (and more) for free, run. I did it yesterday and well, it’s nice to try this brand-new piece of eye candy. the interface is completely new, you won’t find the usual drop down menu but with some imagination you’ll manage to save/create/open a new document by clicking on the big roundy Office logo on the top left corner. More user friendly? Perhaps, once you get used to it. It STILL doesn’t have a tabbed interface, so you STILL have to clutter your taskbar if you want to keep more than one document open.
At any rate, it does the job, exactly in the same way as it did in the previous versions.
I use it if people ask me to, and for writing stuff which doesn’t need to be formatted with a particular markup or style but rather look nice and have pictures embedded.

Writely – Now this is much more fun. A online, AJAX-powered word processor recently acquired by Google. IT’s currently in closed beta, but I was lucky enough to get an account before they closed registrations and I can invite people to use it.
It’s nice. It’s nice if you have to work with MS Word documents or create PDF files, and it supports the most essential features offered by desktop word processors, plus some more, really convenient functionalities.
It can import MS Word documents pretty well and also any kind of text file, so that you can edit it online anytime and anywhere. You can star, tag, archive, edit and delete your documents in a really easy way and – which is one of its killer features – you can grant access to certain documents to collaborators for editing or viewing. Other word processors out there offer similar features, but Writely is by far the nicest to use and perhaps even the more advanced. I recently wrote a couple of articles about CakePHP (coming soon-ish to some online magazines near you) and then gave access to gwoo and PhpNut for editing, so that they could check the code snippets, in particular: it was a success. Magazine editors were happy and impressed as well.
Another really wonderful feature is version support. I discovered this recently: when you edit a document and save it, Writely automatically creates a new version of it, storing the old ones as well, so that you can even compare them to highlight differences if you wish: a great feature to keep track of the editing process and know exactly who edited which. When I noticed it that was it, Writely has become my online repository for my articles and writings.

Cream – I discovered this a while ago, and it’s perhaps the most multi-purpose editor out there. It’s built on top of Vim (respect+) but it has a friendlier interface by default, and that’s exactly what I’m using right now for typing this post. The reasons are simple: it supports ANY kind of file format and any character encoding. There’s an highlighter for everything, including BBcode and textile, and of course you can make your own. It also includes spell checking on-the-fly which is missing in many simple editors.
Whenever I have to write something which requires some particular formatting or markup I use Cream, it does the job pretty well, and whenever I feel brave I can always switch to “expert” view and challenge my vi skills ;)

That’s pretty much what I use for writing articles, posts, and other documents… I tried other alternatives like RoughDraft or similar programs but I’m now really happy with these three applications. Commercial “writer’s programs”? There are some out there, but who wants to spend 40$ or more for something which offer less than MS Word when you can use OpenOffice and Writely for free?

Writing more articles...

h3rald@h3rald.com — Sun, 14 May 2006 04:26:00 -0000

Yes, I know, I’ve been slaking a little bit, and haven’t posted on my blog in a while. Well, I actually didn’t slack at all in these days getting ready to start my job, looking for a damn fitted kitchen for my house and… writing more articles.

Nothing special, and nothing too technical, to be honest, but equally interesting. First of all I updated my An IE Lover’s Guide to Firefox a little bit and people at SpreadFirefox.com and FirefoxFacts liked it. Glad to hear that, unfortunately some guy who wrote about Firefox Myths wasn’t too impressed, but at any rate he read it anyway.

OK, this wasn’t a new article at all, but this one is fresh, at least. It’s about a Swedish guy who decided to emigrate to India pursuing an ideal: writing for his own opinions and ideas. And he gets paid for that too! After reading more about him on his website I decided to write something about him. An interesting and rather unusual read. Pity that some sections of his homepage are in Swedish only.

Finally, yesterday I felt inspired and decided to write another roundup featuring ten popular social bookmarking websites. Trying all those services was fun, with a few exceptions of course. The bad news is that there are already various reviews about social bookmarking sites and thus the Digg folk doesn’t seem to be particularly interested in reading another one, but hey! After all I can’t expect of getting dugg for every roundup I write, can’t I?

That’s about it. And what about the CakePHP article I promised long ago to CakePHP beginners? It’s done, written and ready to be published! Unfortunately the magazine I submitted it to is taking quite a bit to review it and – most important – to tell me whether they’ll publish it or not. Let’s hope for the best.

The Internet Philosopher

h3rald@h3rald.com — Thu, 11 May 2006 11:00:41 -0000

Recently I got this rather short email from a guy named Daniel Lampinen:

Hi. Respect for being an internet addict – that’s good. I have moved to India just to afford and get time to be on the internet as much as possible:

http://www.ropix.org/english.html

Spam? Yeah, must be: I get this kind of stuff all the time, and this looked like another person asking for money. Or maybe not? After all this guy is not asking for anything in his mail, he’s just telling me something about myself and perhaps try to get me to visit his site¹. I did indeed – after all it was just one click away – mostly for curiosity.That website was one of the most plain ones I’ve ever come across, perhaps to help the visitor to understand that content is the only think that matters, not design. Daniel seems to be Swedish, and he immediately apologizes for his imperfect English: indeed there are some mistakes here and there, but I could understand enough about him, his way of living and his beliefs that I decided to write this article about him.

An Internet Philosopher

“I’m trying to live for my opinions and ideas”

This is Daniel’s “statement” which guides his entire life. He lives for his opinions and ideas, he lives to debate them with others, to talk to others about them, and eventually getting money for doing so: that would be his ideal way of living, and he partly realized it already.
It all started last year (2005), when he was a mailman in Stockholm: that was a boring job, probably like a million other jobs anywhere in the world. He didn’t want to do that, and – believe it or not – he didn’t want a business career either: he just wanted to spend time on the Internet, creating things. Not cool websites or successful e-businesses, just express his own opinions, thoughts and ideas and spread them online, he defines himself a philosopher, and yet I could not find anything better to define him: he literally lives for his thoughts.

A few months ago the Italian Telecom broadcasted one of the most peculiar adverts I’ve ever seen: they were portraying an hypothetical past, where Gandhi was appearing on TV, on the Internet, on mobile phones, on big screens in the streets pronouncing one of his famous speeches. The advert ends with a sentence like “Imagine what could have happened if he could have used our communication systems”, trying to promote Telecom’s services, and it has been criticized² many times for this.
I immediately thought about this advert while reading Daniel’s homepage. Obviously he’s far from being Gandhi, but at least he attempts to live in a simple and honest way and tries to communicate with as many people as possible. And he lives in India, he recently moved there from Sweden mainly because it’s much, MUCH cheaper than any country in Europe or in the rest of the Rich World.

From what I could read about him, his life is quite simple: he tries to spend as little money as possible and not in futile things. He lives in a cheap hotel in Puri, India, where he can access the Internet – that’s all that matters. Perhaps it may sound a bit freaky, but certainly not as freaky as going out getting trashed every night, buying drugs or waste money on trendy clothes – at least from someone’s point of view.

“Yeah, OK, it’s all good so far but how can he live like that? Has he got a job?”

Yes and no – not in a traditional way, at least. He sells stuff, his thoughts, ideas and writings to be more precise, and no, there are no set prices: he goes “[…] by this principle (the Annalakshmi³ principle): pay as much as you think my work is worth.⁴”.
It’s quite similar to charity and it’s an interesting idea, whose success highly depends on the conscience of the giver: the more honest his soul his, the more he’ll give.

Business Talk

Don’t call him a beggar. Daniel has his own way of seeing the economy of the Rich World and also his own views when it comes to money:

“This should be mentioned: give money to Unicef instead of to me. But give money to me instead of buying a expensive new couch.
[…] If I can inspire you to consume less, it may be worth some money. How would the world look like if everybody payed each other because they wanted to, not only because they legally had to? Pretty good, right? On some places in the world there’s today restaurants where you can pay as much as you thought that the food was worth. See this like a newspaper or a book that you can choose to pay for.

There’s plenty of different policies on what you should put your money on. On of the policies is to follow the market totally (except when it comes to classic charity). That one use to result in that you think it’s ok to buy a Gucci bag for $1000 but think it’s out of the question to give something to someone that “doesn’t wanna work for the money”.

[…] It can even be fun to get fooled by a souvenir salesman in a warm country – if you let go of some of the pride and the “millimeter justice”. Do that. You can still give as much or more to Unicef. I prefer a society where people put money on other people – both those struck by a catastrophe and rich people in your country – instead of buying un-necessary stuff.⁵"

Daniel accepts donations in many ways⁶, and it must be noted is that his supporters may even choose how he should use his money, you can tell him what to buy or not to buy, and he’ll respect your decision: someone told him not to buy drugs and he never did, while another asked him to buy good food, and maybe a beer at local restaurants, and he did exactly that⁷.
If you’re curious about what he buys, Daniel added a list of expenses⁸ to his site which diligently updates every time he spends money. Prices are in indian rupees (1$ is about 45 rupees!), and it looks like this:

10 Bread
9 Tip to roomservice
30 Internet ticket
10 Drinking water
40 Riksa taxi
10 Muffins
10 Bananas
25 Bread and chips
10 Tip to roomservice
36 Candy
15 Bread
20 Internet ticket
12 Tip to roomservice
20 Tip to roomservice
7268 Hotel room for 8-18 April (plus food+bewerages+internet+laundry)
15 Tip roomservice

In a nutshell, when it comes to money and buying things, Daniel lives by this simple rule:

“Work with unwanted things as little as possible, consume as little as possible, communicate as much as possible”

But is it really that simple? Could you live like him and still be happy? Certainly he has a big advantage: he lives in India, where everything costs much less than in Europe or the US. If you decide to try, he can help: he can give anybody suggestions on how to live cheaper and even keep you motivated to do so, and all he asks in exchange is what YOU think his suggestions are worth. All the payments for this service must be made through a Swedish company⁹, which is technically his employer.

He can also sell “ideas” in the same way: you start emailing him explaining your situation and your needs, and he’ll try his best to come up with a solution and his own opinions. You won’t believe it, but a Swedish company¹⁰ was really pleased to hear his opinions and thoughts about innovation and used his suggestions to improve their services.

An Internet Addict

Perhaps one of the most interesting things about Daniel’s website is his journal. Not a proper blog, but just a single static webpage hosting all his daily thoughts: you can’t comment to them, but reading some passages may be interesting enough.
The best way to do so is trying to search for a particular word (in Firefox it’s pretty easy) and read what he wrote about that, I tried with “Internet” and here’s something I came across:

“Now I’m finally realizing my two year old plans to be in a poor country. The only thing I’m gonna do is thinking, and surfing on the internet, see how long my money will last, and try to get new money to my VISA card by doing work that can be done with a brain and internet, for example producing ideas and point of views to companies in rich countrys. What’s good for everybody, is that I don’t need many dollars/euros to survive.”

This was one of his early posts, and yes, that’s exactly what he started to do…

So, I’m living at the internet. Hotel room, beach, internet. That’s pretty monotonous. But all together better than better than s[**]t job. I’m gonna contact medias that cover the internet and offer to write things in behalf of a person that have filled his life with only internet.

Internet, internet, internet. I’m happily addicted to something that makes me smarter and finding the right people. The only thing you need is a cable. People are crowding at the internet cafes here at the tourist street by the beach, and it’s a nice atmosphere.

An happy internet addict. Although how good this addiction is can be debatable, Daniel seems to have found his perfect way of living, and the only thing he needs is an Internet connection and his brain.

“Yesterday I searched on Google for the swedish words for “I am an internet addict” and e-mailed the words “respect for being an internet addict – that is good” to the bloggers that had written the sentence “I am an internet addict” during the last year."

Yes, that’s exactly the message I got by email a few days ago. At first I must say I found it even a bit offensive: “I am not an Internet addict! You might be, but I’m not.” – He obviously didn’t mean to insult neither me nor any other blogger he mailed: for him, “being an internet addict” is probably one of the best things people – especially young people – can do.

Shocked? Yes, it’s understandable: we hear a lot about Internet addiction in these days, and I was reading in a recent study¹¹ which pointed out that:

“[…] When 54 percent of Internet addicts say they have a history of depression, 52 percent drug or alcohol abuse and 34 percent an anxiety disorder, it seems even clearer that cyberspace is just another place for unhealthy and self-destructive behaviors to manifest themselves.”

Is it though? Daniel Lampinen truly admints he’s an Internet addict, but he most definitely doesn’t have any history of drug or alcohol abuse:

“On [the] Give me money [page] there’s now a list of demands from the givers. The first demand come from the latest giver: no drugs. Which I’m fine with. As you can see on What I’m buying, I’ve only bought one joint (in Christiania in Copenhagen). And that was just a statement because I think others is gonna be free to do it. I never take anything to “get away from reality”, or to “have fun”. Not even beer, which I only take to relax. That’s how dull I am. The reality rules."

There you are.
So why did he choose to become an Internet addict? Well, most definitely because he was tired of the Rich World’s society: he had a boring job which he didn’t enjoy, and he simply realised that the Internet could – at least sometimes – be better than ordinary life. He openly admits he’s a weird human being, and he’s fine with that, but you can be sure of two things:

he’s totally, absolutely honest, in anything he does, and he’s not afraid to express his own opinions without adjusting them according to the people around him
he maintained his individuality at the cost of living in a poorer country

How many people in the Rich World can accomplish either of these things? Please raise your hands…

Notes

Very special thanks to Daniel Lampinen for allowing me to write about him and providing all the pictures for this article.

¹ Daniel Lampinen’s website, English version.

² Gandhi e Telecom Italia – Comments on the famous Italian advert. [Italian]

³ Annalakshmi – A non-profit organization dedicated to bringing the joy of Indian culinary, visual and performing arts to one and all.
Annalakshmi is an international chain of vegetarian restaurants that augments its dining experience by showcasing Indian arts and handicrafts as well as cultural dance and music performances. Inspired by the Hindu concept for Abundance, Annalakshmi operates on the basis of “Eat as you Want, Pay as you Wish” where the guest decides not just what to order but also how much to pay.

⁴ From Daniel Lampinen’s UI Ideas page.

⁵ From Daniel Lampinen’s Money page.

⁶ Daniel’s Money page lists all possible ways to dive him money, most notably:

Paypal
His IBAN bank account number (an international number):
SE1580000008201644439081
With this code: BIC. SWEDSESS
His free page.

⁷ It’s documented in the Gustav 100Kr page.

⁸ Daniel’s list of expenses.

⁹ F-Bolaget AB

¹⁰ Intip

¹¹ Is Internet addiction a real problem? – Arstecnica.com

Baking a new CakeArticle

h3rald@h3rald.com — Thu, 13 Apr 2006 14:21:00 -0000

Too right. Enough being a lazy writer, it’s time to seriously produce something. I could sit here and pretend that long blog posts can make up for the lack of new articles, but I’d like to write something proper and new. Judging by the latest stats people come here hoping to find either a blog entirely devoted to CakePHP or some CakePHP related content. Well, actually they can find quite a bit, but I’d like to be able to sport more Cake-related articles, bookmarks, and posts. My main problem is that I could add ten bookmarks about Cake right away, but the latest addition showed on the front page would feature only bookmarks, which would be bad (yes, I do worry about silly things). At the moment this blog is the second easiest way to provide fresh content frequently enough to encourage visitors to come back, but articles could be even better.

Without further ado, I hereby announce that I am working on some new articles on CakePHP, at least one. I’d like to write something technical about CakePHP’s advanced features, because that’s where the current documentation is lacking, at the moment: associations, caching, some advanced components… they are topics which seem to interest those bakers who already baked their first cake and are now looking for some more icing.

Interested? Good! Sadly, that’s not what I’m going to write now, at least not the first article I’ll be releasing. Please stop calling me names, there’s no need to say that I’m just a lazy coward who doesn’t want to get his hands dirty and write some tough stuff. And stop pulling those sad faces! Think about… new bakers. There are new people learning about Cake and I know there are, I just discovered one yesterday almost by chance: he seems to be really enthusiastic about Cake, judging by his latest post (OK, nevermind the pic).
Those people are mostly more-or-less experienced PHP programmers who want to find an answer to all their development problems and annoyance. Well, my good friends, the answer lies in Cake. Cake can save us all and bestow powerful blessings of Good PHP Design and Well-structured Programming upon our messy spaghetti code!

I almost considered writing a humorous article about Cake, but luckily I changed my mind. My old CakePHP article is already a few months old and was written when Cake was in pre-beta. I feel it’s time for a more up-to-date howto and introduction to our framework, something maybe not as lenghty but easily readable by almost anyone interested in starting to learn about Cake.

Baking lessons. Yes, that’s it. I’m currently writing an article divided in ten lessons which could potentially turn casual cowboy coders into (apprentice) bakers. That could be easy for those already enlightened by OOP and MVC, and perhaps more difficult for others: at any rate, I’ll try my best.

Project Gutenberg: The What, When and Why

h3rald@h3rald.com — Sat, 10 Dec 2005 11:55:28 -0000

I always liked reading Shakespeare, and I always wanted to have a copy of every one of his plays, tragedies and sonnets on my bookshelf ready for consultation, but such things always seemed unrealistic because I had neither the space for them nor the time to find them all nor the money to spend on them when I did find them.
Now I can store the complete works of William Shakespeare directly on my mobile phone, and they take up as little as 1.4 MB compressed...
Origins

Even if you never heard the word ?e-book?[1] before, you can probably guess its meaning: electronic book, or a book in digital format. What you probably don't knoe is that people started copying books into digital format nearly as soon as computers were available to the public, and maybe even before: the first e-book was created in 1971.

That year, a student at the University of Illinois named Michael Hart was given the equivalent of $100,000,000 (or $100,000, or $1,000,000 - there is no official estimation) in computer time. Basically, since he was friends with some of the operators at the Materials Research Lab, he was given an operator account on the Xerox Sigma V mainframe, which later became one of the 15 nodes that developed into the global network that eventually became the Internet. At that time, having that much computer time at your disposal was indeed a great privilege, and Hart felt that he had to use that time for something useful that could in theory generate a profit - not an easy task when you consider that only a limited amount of people in the world had access to a computer, and that those computers weren?t even connected together.

Foreseeing an era where computers where interconnected and regular people had access to them, Michael Hart thought that virtually all texts and books could be made available in digital format, for free, to anyone who wanted to read them. Certainly, such a project seemed quite unrealistic and excessively time consuming at the time; nevertheless, he decided to start copying the first book himself, the Declaration of Independence of the United States, which he was carrying in his backpack.

Project Gutenberg[2] was born with that one single text, and it has grown through the years. Today, there are more than 16,000 e-books available to download and read.

What is Project Gutenberg?

By that name, Michael Hart probably wanted to define the project?s scope and vision: an idea as revolutionary for the diffusion of literature as the invention of moveable type printing[3] in the 1450s.

The mission of the project can be summarized as follows[4]:

[center] "To encourage the creation and distribution of eBooks."
[/center]

In order to achieve this, Project Gutenberg is set up such that anyone can contribute to it, in many different ways. It is run completely by volunteers, hundreds of people around the world who share the same ideals and believe that literature should be freely available to everyone at virtually no cost.

The Internet serves this purpose magnificently: it is possible to download all of the over 16,000 free e-books from the Project Gutenberg website[5] in different formats and many different languages[6]!

However, having such a large amount of books available within a few clicks can make people forget about how time consuming the process of making one single e-book is: originally, after acquiring a paper copy of the book, Gutenberg?s volunteers had to transcribe it themselves, typing every word from the beginning to the end. Then the book had to be checked for mistakes before it was accepted into the Project.

Producing a single e-book can therefore take many people and many hours from beginning to end, and presumably this was one of the reasons why Project Gutenberg was criticized for being more of an utopian ideal than a tangible reality: every year since its creation people have doubted the project, accusing Hart of pursuing an impossible dream, and prophesying that fewer and fewer people would join the team and that there was no future for Project Gutenberg.

Oddly enough, they were all wrong: not only is the Project still active today, but the number of books released every year has grown consistently over time, from a few dozen in the early days to thousands per year now.

More and more people became involved, partially because they share the same ideals and partially because it has always been easy to get involved[7]: Project Gutenberg strives to remove all the institutional barriers which could potentially interfere with members? motivation; they try not to impose any restrictions, and they don't support perfectionism. It is believed[8] that there shouldn?t be any proper or standard way to release e-books, but instead many different ways, to appeal to many tastes: the Project doesn?t support any particular standard for releasing ebooks, although it normally takes the simplest path. Therefore, the majority of the books are available in Plain Vanilla ASCII, i.e., texts are written using only ASCII characters, and bold, italicized or underlined words are capitalized instead. While this format has the most limitations, it is also the most portable.

At this point, you might wonder why they don't just scan the original books, and make them available as image files or PDF files. While it would be much faster, it also has disadvantages, such as large file size and an inability to be displayed at particular resolutions; a scanned book probably wouldn't be readable on a PDA, mobile phone, or other equally small device.

Nonetheless, scanners do play an important part nowadays in the process of making an e-book: texts are no longer copied manually if a printed edition already exists. Instead, they are scanned with OCR[9] and then proofread twice before being accepted. The (un)official procedure recommends scanning at least one page a day, having it proofread once by someone in charge of doing so (a ?junior? proofread), and then again by a more experienced member. This has undoubtedly sped up the process.

Not All Books Are Equal (for now)

By looking at some of the titles available on Project Gutenberg, you?ll notice that most of them are classics or relatively old works: for example, you won?t find the latest Harry Potter[10] available for download.

Since all of the books at Project Gutenberg are free to download (more details of the license will be given later on), and therefore not subject to fees or copyrights, only books in the public domain[11] can generally be included in the Project.

Public domain includes all those works of art whose intellectual property cannot be legally claimed or exploited by any person, institution or legal entity, and therefore belong to all mankind. In the case of books, copyright can expire only if some particular conditions subsist:

The work was created and first published before January 1, 1923, or at least 95 years before January 1 of the current year, whichever is later.
The last surviving author died at least 70 years before January 1 of the current year.
Neither a

perpetual copyright

Now we can see why there are not very many new publications available in the project, and that?s really frustrating for Michael Hart and other volunteers:

"In the USA, no copyrights will expire from now to 2019!!! It is even much worse in many other countries, where they actually removed 20 years from the public domain. Books that had been legal to publish all of a sudden were not. Friends told me that in Italy, for example, all the great Italian operas that had entered the public domain are no longer there... Same goes for the United Kingdom. Germany increased their copyright term to more than 70 years back in the 1960's. It is a domino effect. Australia is the only country I know of that has officially stated they will not extend the copyright term by 20 years to more than 70."[12]

After all these considerations, we can take a closer look at Gutenberg?s license[13] which comes in two different versions: informative and normative (?legalese?, as they call it), the latter of which is the real document. Luckily, the non-legalese version is simple and complete enough: basically PG releases books which are either in the public domain or ? if copyrighted ? the author gave express permission to re-distribute them. The difference lies in the fact that if you remove PG?s trademark and license from a book which is in the public domain, you can re-distribute it freely on your own, but if the book is copyrighted and permission to distribute was given only to PG, you?ll have to contact the author to obtain permission.

Furthermore, anybody can use the PG trademark when distributing verbatim copies of a book, with no changes (re-formatting is allowed); if you want to charge money for the copies you distribute, you have to pay royalties to PG.

Satellite Sites and Similar Projects

Michael Hart was ? and still is ? an authentic pioneer in his field: he had the idea to create the largest free library on the Internet to ?Break Down the Bars of Ignorance and Illiteracy?. A lot of people thought he wouldn?t achieve anything, but his dedication and perseverance were simply so exemplary that more and more people got involved, a few satellite sites were created and similar projects were started in all over the world sharing the same goals.

Hart is obviously aware of the fact that there are also some sites selling e-books, but he explains that neither those sites nor any other free online library should be considered a competitor to Project Gutenberg: they all contribute to the diffusion of e-books.

One of the most important satellite site of PG is ?Distributed Proofreading?[14] which is now considered the main source of PG books: every month more than 100 books are proofread by hundreds of volunteers who can register on the site for free and then get added to the project. The key concept of this parallel organization is that a single book can be proofread by more than one person at the same time, and thereby speeding up a project which would be otherwise very difficult to coordinate.

Another site which helps the main project is HWG, the HTML Writers Guild[15]. It aims to convert PG?s plain text ebooks into more feature-rich HTML documents: by using a mark-up language it is possible to add footnotes and it can be analyzed easily by automatic tools.

Although Project Gutenberg releases well-known books in many languages, a few sites officially affiliated with the project were created to focus particularly on their regional literature and works. That?s the case for both Australia[16] and Germany[17], for example; they both focus on their own national heritage. Regarding the latter, they recently claimed their own copyright for their e-books, and thus a new foundation is in the process of being created: Project Gutenberg Europe[18] which aims, among other things, to address the myriad copyright issues and laws of the EU.

Last but not least, there?s an interesting discussion[19] about similarities and differences between Project Gutenberg and Wikisource[20] a Wikipedia[21]?s sister project aiming to create a free repository of texts which are either in the public domain or licensed under the GFDL[22].

Wikisource people obviously noticed that their project was quite similar to PG, but with an important difference: their texts were formatted and freely editable by any user who was able to spot a mistake or inaccuracy; PG doesn?t offer this. In this context, Project Gutenberg was sometimes blamed for allowing inaccurate material to be included in the project: this was due to the fact that even if PG uses Distributed Proofreading website to proofread e-books, this is often not comparable to a wiki system. However, in PG's defense, wiki articles, being much more open, are subject to much more vandalism, and therefore must be more closely watched. One can imagine a high school student changing Hamlet to read "To be or not to be, who gives a crap."

However, the members of Project Gutenberg have proposed a sort of mutual cooperation between PG and wikisource: wikisource should maintain a broader scope, focusing not only on literary works but also on quotations and other kind of texts, and at the same time provide some revised edition of some book to Project Gutenberg.

The Future of Project Gutenberg

Project Gutenberg demonstrated the ability to grow considerably during its over 30-year existence. During that same time, copyright laws were extended, and some new technologies tried to intimidate the Project, which seems to remain relatively unchanged. However, last year a long-awaited DVD containing all the Project's e-books was released, showing the world that PG can keep up with the progress of technology to a certain extent.

One aspect that makes PG a successful project even today is its ability to adapt: CD-ROMs and a DVD were released, OCR was almost immediately taken into consideration, and since last year, all e-books have been released in both plain text and HTML format: there are still no fixed standards or rigid guidelines, but common sense seems to prevail over chaos, and for now, the system works.

So far, Michael Hart showed the entire world that a single person can do a lot when pursuing a noble goal. Call him an idealist, call him a dreamer, but he surely created something able to gratify and motivate him and his fellow volunteers forever:

?I can't think of anything more rewarding to do as a career than Project Gutenberg. It is something that will reach more people than any other project in all of history. It is as powerful as The Bomb, but everyone can benefit from it.?[12]

Notes & Further Readings

[1] Ebook, Wikipedia page ? http://en.wikipedia.org/wiki/Ebook
[2] Project Gutenberg, Wikipedia page - http://en.wikipedia.org/wiki/Project_Gutenberg
[3] Movable type, Wikipedia page - http://en.wikipedia.org/wiki/Printing_press
[4] Project Gutenberg FAQ0 - http://www.gutenberg.org/about/faq0
[5] Project Gutenberg Official Website - http://www.gutenberg.org
[6] Project Gutenberg?s catalog - http://www.gutenberg.org/catalog/
[7] Project Gutenberg?s volunteering page - http://www.gutenberg.org/info/volunteer
[8] Project Gutenberg FAQ3 ? http://www.gutenberg.org/about/faq3
[9] Optical Character Recognition, Wikipedia Page ? http://en.wikipedia.org/wiki/Optical_character_recognition
[10] ?Harry Potter and the half-blood prince?, Scholastic Inc. website - http://www.scholastic.com/harrypotter/books/prince/index.htm
[11] Public Domain, Wikipedia Page - http://en.wikipedia.org/wiki/Public_domain
[12] ?The Second Gutenberg Interview with Michael Hart?, Sam Vaknin, Ph.D. - http://samvak.tripod.com/busiweb29.html
[13] Gutenberg Project license ? http://www.gutenberg.org/license
[14] Project Gutenberg?s Distributed Proofreading - http://www.pgdp.net/c/default.php "> http://www.pgdp.net/c/default.php
[15] HTML Writers Guild Project Gutenberg ? http://gutenberg.hwg.org/
[16] Project Gutenberg Australia ? http://gutenberg.net.au/
[17] Project Gutenberg Germany ? http://gutenberg.spiegel.de/
[18] Project Gutenberg Europe ? http://gutenberg.nl/
[19] Wikisource and Project Gutenberg, Wikisource page ? http://wikisource.org/wiki/Wikisource:Wikisource_and_Project_Gutenberg
[20] Wikisource main page ? http://wikisource.org/wiki/Main_Page
[21] Wikipedia main page ? http://www.wikipedia.org/
[22] GNU Free Documentation License ? http://en.wikipedia.org/wiki/Wikipedia:Text_of_the_GNU_Free_Documentation_License "> http://en.wikipedia.org/wiki/Wikipedia:Text_of_the_GNU_Free_Documentation_License

Name	Explanation
Chuncking	Writers should group information into small, manageable units.
Relevance	Writers should make sure that al information in a chunck relates to one main point (function or purpose).
Labeling	Writers should provide a label for every unit of information.
Consistency	Writers should use similar labels, word, formats for similar subject matters.
Integrated Graphics	The use of tables, images, diagrams and lists is encouraged.
Accessible Detail	Documents should provide sufficient details where necessary, to make the information more accessible for the readers.
Hierarchy	Small, relevant units of information should be organized into a hierarchy.

Name	Definition
Procedure	Set of steps to obtain a specified outcome
Process	A series of changes through the time for some purpose
Structure	Something which can be defined into multiple parts
Concept	Group of physical objects, conditions, relations, …
Principle	Statement of what should be done, assumptions
Fact	Statement presented with no supporting evidence
Classification	The sorting of a group of specimen into classes