Annoucing the Merb open source book

Matt Aimonetti compares the search growth between Rails and Merb

Here is a graph representing the growth of of web searches related to the programming category. This is not a comparison of the amount of searches made.

We can see a huge peak around the time Merb 1.0 got released. More and more people are looking for information about what’s already being called the “Ruby web framework for the enterprise”. This is obviously a very interesting and encouraging trend. The problem is that unfortunately, the reality is that when you search for Merb documentation you don’t get very useful results.

Worse still, the main complaint we get is the lack of end user documentation. No fancy screensavers, no demo applications, just a simple, well organized but not expansive wiki. Don’t get me wrong, I’m really proud of our wiki. The wiki was restarted from scratch during the 1.0 RC era and we have some really decent documentation including a step by step BDD example with code on GitHub. The problem is that wikis, in general, are not easy to read when you want to learn a new technology. But they are great when you look for answers to a specific question, like: how do I use authentication, how do use transaction specs with RSpec…

The Ruby community is used to not having great open source documentation and to purchasing books written by experts. I remember when I joined the Ruby community, the company I was working for was looking at three frameworks: one written in PHP, the other in Python and the last one in Ruby. The Python framework was the fastest but didn’t have a testing harness. The PHP framework had great documentation but was PHP (no comment).  And the Ruby framework almost did not have any documentation but had great momentum. It also had a book released which kind of compensated for the lack of documentation. (I don’t think we would have picked the Ruby framework if all the engineers did not fall in love with the language :p)

Merb has 4 books in the process of being written, 2 of them already available in Beta. This is really exciting but it doesn’t answer the need of two types of audiences:

  • People who decide to give Merb a try and don’t have much time/patience/money ;)
  • People outside of the English speaking world (yes, even though according to Hollywood, even aliens speak English, the reality is that a lot of people prefer to read documentation in their native language)

Looking at other frameworks, a lot of the well known ones offer free books. Django has its famous Django Book, Symfony has its book

To address the needs of people who want to get started quickly, we probably need to write some great tutorials. I think we will soon focus on that. People have already started writing awesome tutorials on getting started with glassfish and Merb and other cool things. However, most of these tutorials are designed for people who already have some Ruby knowledge. So the core team will probably need to help the community get a bit more organized and write some good simple tutorials for total newbies. However this is not really hard to do.

The real challenge for me is to reach the foreign audience. As you have probably noticed by the amount of English mistakes I make, I’m not a native English speaker. I remember learning English by asking my mom to translate computer messages I was getting when using my cousin’s Amstrad CPC and my dad’s Amstrad PC 1512. The first English words I remember learning were: “Game Over” and “insert the floppy disk” :)

Talking with Brazilian Ruby evangelist Fabio Akita about his books, he reminded me how hard it is to get up to date IT documentation in your mother tongue. People talk about Globalization but in a time were knowledge is power, people outside of the US are still getting IT books one to two years after their US release.

PDF books make things a bit easier but you still need to be able to understand and of course you need to hope the online shop will accept your “foreign” card.

Merb book

The Merb team has decided to support the documentation effort. At first we thought about updating Matthew Ford’s Merb 4 ninja book. But the project was started when Merb 0.3.x was released and needed a huge amount of work to be brought up to date.

After talking with Matthew, we decided it was probably better to start a new project backed by the core team. I quickly put together a simple localized Merb app rendering markdown files using awesome maruku.

The app is simple to use, simple for editors to contribute content, simple for translators to do their job.

We gathered three Merb book authors: Yehuda Katz, Foy Savas and Matthew Ford and worked on an initial table of contents. At the same time, I got in contact with Fabio Akita, Mathieu Fosse and Makoto Kuwata to see if they were interested in leading the translation in Portuguese, French and Japanese. Everybody got really excited and wanted to start as soon as possible. Here is a short list of goals for the book:

  • From the community, for the community
  • Creative Commons share alike type copyright
  • Simple, organized and up to date documentation of the Merb stack
  • Focus on the common use cases
  • Early localization to allow centralized, up to date documentation in various languages
  • Export to static HTML and PDF

The initial work is available in my GitHub repo and we are planning on publishing an updated version of the book daily. The book will be tagged at the same time as Merb releases, to allow people to go back in time and check the book for a previous version of the framework.

If you are interested in helping, it’s very simple:

add/modify content:

  • clone the book repo
  • modify/add content
  • rebase to avoid conflicts
  • send me a pull request

translate content:

  • Find out who the translator leader is for your language (check the readme file in the repo)
  • clone the book repo
  • add translations
  • send the leader your pull request

If there is no translator leader for your language, contact me.

I really hope to be able to add Spanish, German and Chinese pretty soon. If you are willing to lead the translation work for these languages, please contact me via email (mattaimonetti at Gmail or via github).

Join the mailing list if you want to get the latest news or discuss the content.

Google Groups
Subscribe to the merb book mailing list
Visit this group

Finally, Yehuda has been working on another very simple Merb app to let you find available methods and their documentation in context. RDoc is fine, but how do you know what methods are available when you are in a view, and what about in a Model? Once again, the concept is to make your life as developer easier. For a long time we have focused on the framework itself. It’s now time we focused on making it easy to use so more people can enjoy the power and flexibility of Merb.

Of course, all of this is done for you. So if you have any comments, concerns, advise, feel free to contact us directly or leave a comment.

Similar Posts

, , , ,

  1. #1 by Liam Morley - December 4th, 2008 at 23:42

    This is really great news, thanks for getting this started!

  2. #2 by Liam Morley - December 4th, 2008 at 23:45

    ps have you guys thought about potentially using for rdocs?

  3. #3 by Matt Aimonetti - December 5th, 2008 at 00:00

    @Liam thanks for your support. We actually looked at written by Josh Knowles. The problem is that we need to merge docs from multiple gems and we want to filter out private methods to only show methods developers should use. Finally, wycats’ app reorganizes the documentation to look for methods in context, something we will be able to use inside IDE’s contextual helps.

  4. #4 by jc - December 5th, 2008 at 00:42

    Sounds great! Hope to help out.

    Any plans to add some inline commenting like on Django? That’d be rad

  5. #5 by Matt Aimonetti - December 5th, 2008 at 00:46

    @jc we are talking about it, first we’d like to finish the book, get a nice PDF export and then we’ll probably add contextualized comment like the djangobook did. It doesn’t make much sense to do that until we finish a first version of the book tho ;)

  6. #6 by Softmind - December 5th, 2008 at 01:57


    Very soon… I shall start supporting this book in Gujarati and Hindi language for Indians.

    This is a great move by Merb Team.

    Just Go ahead… we all are with you.

    SoftMind Technology

  7. #7 by Carlo - December 5th, 2008 at 02:12

    Great initiative!

    A little suggestion: maybe a short series of (small) screencasts could help a lot in spreading Merb…

  8. #8 by Dick Davies - December 5th, 2008 at 02:18

    That’s great news; we merb newbies really need something like this.

    One thing I would say is that I’ve found the number of old merb tutorials turning up on Google
    to be a real put-off; you work through them on 1.0, nothing is where it should be, and you assume
    the framework is still beta.

    I understand the amount of work that goes into updating old documentation, but is there any way to
    get them offline? A few recent tutorials would be better than dozens of outdated ones.

  9. #9 by TJ Stankus - December 5th, 2008 at 03:41

    Great news! Looking forward to digging in and helping out.

  10. #10 by Matias - December 5th, 2008 at 04:11

    Can you enlighten us and tell the names of the four Merb books being written?

  11. #11 by Andy L. - December 5th, 2008 at 05:24

    I totally agree with Carlo — Screencasts, on Merbivore’s main page (well, linked from there, with screenshots or some appealing graphics).

    I still remember that intro screencast on the Rails site… — It blew me away! Now it’s Merb’s turn. ;)

  12. #12 by Steve I - December 5th, 2008 at 07:09

    This is excellent and timely.

    Just thinking about spending some time learning merb.

    Although rails has some excellent resources I don’t know of any equivalent.

    This sort of thing will encourage people to contribute and I will certainly try once I feel confident enough.

  13. #13 by Matt Aimonetti - December 5th, 2008 at 09:17

    @Softmind that’s great, we, westerners, have a tendency to believe that all Indians speak English so why bother? I’m glad you will help. Join the mailing list and work on your project when you can. My suggestion is to try to get a team of people to help you out.

    @Carlo Definitely, we really should do that!

    @Dick Davies I agree, I spent some time last night going through the top google results and try to edit the content when available or to point to more recent documentation. We should really try to find all the old articles and at least add a comment.

    @Matias sure thing: they are on the wiki, (scroll to the bottom) Merb in action, The Merb way, Beginning Merb and the last one is Merb: What You Need to Know.

  14. #14 by vire7 - December 5th, 2008 at 09:40

    This is fantastic news. I used to wonder if frameworks were invented to sell books, then Django did their thing and I longed for the same thing in the Ruby web development world.

    That said, I’m fairly green (two Rails apps, one Django under my belt). I’d love to know enough to contribute to such a project some day. Count me in.

  15. #15 by Star Trader - December 5th, 2008 at 11:44

    I’ve started working on adding English content. After the rant I gave about no documentation for real user it seems only fair. I’ve also added a Wiki page to the mattetti/merb-book project to try to coordinate what information goes in what chapter as it is not clear.

    @Andy L. and Carlo I’ve been interested in doing some Merb Screencasts, but could never come up with a good topic. If you have any suggestions post them to my blog and I’ll see what I can do.

  16. #16 by khelll - December 8th, 2008 at 09:15

    Hi, i just want to start working on tha Arabic version of the book, however, Arabic language has the RTL form, which needs us to change the alignment to right, i have modified the master.css like this:
    /*master.css (line 101)*/
    #book-content {

    But i don’t know how do you tend to do that in project itself, if the user choose the Arabic version of the book, would u load another css file or what?

  17. #17 by Matt Aimonetti - December 8th, 2008 at 11:30

    @khell, I just added RTL support in the repo and emailed you some information to get started. Thanks a lot for your help.

    - Matt

Comments are closed.