Archive for December, 2008
The good news is that the core team is working hard on improving the state of documentation.
You have the Merb Book on which I am actively work on with a team of 20 people (writers, editors and translators).
You also have the documentation browsing application we are developing to let you browse documentation based on where you are in your app.
Finally, you also have other resources like the Merb peepcode.
The point being that we are actively working on improving the overall state of documentation. However, if you wish to learn more about the internals, how to some more advanced stuff like writing plugins, building your own stack, knowing when to use what component, I would suggest you attend the training class that Yehuda Katz (Merb lead developer) and myself are giving in Phoenix, AZ, January 19-21.
This would give you a rare opportunity to spend time with some of people directly involved with the day to day development of the framework as well as other like minded developers.
3 days ago, I announced the Merb Open Source Book project. I expected that few people would be interested as we heard complaints about the lack of documentation.
What I did not expect, was more than 60 emails and pull requests in 2 days, people committing pages of content, fixes and offering their services to translate the book. The mailing list already has 60+ members and the GitHub repository is being watched by 150+ people and has 50+ forks.
While this could be almost overwhelming, I think this is very encouraging. I have to say that since 1.0 got released we heard a lot of praises and and lot of complaints. The Merb team has been trying to prioritize and address reported challenges one after the other. We recently announced that user documentation was our top priority and we decided to work on two projects:
- better access to the code documentation
- Open Source book
Good news, we have an early beta of the new code browser: http://docsbeta.merbivore.com/
This is still an early beta and only works properly on FireFox and Safari. You’ll notice that currently, only merb-core’s public methods are available. merb-more addition is coming soon.
So what’s special about this code browser?
Contextual search and API filtering. In lay terms, you can see what public methods are available to you based on what you are doing. (are you in a controller, model, the console?)
Open Source Book
I put an early beta online: http://book.merbist.com
This is not a static version yet meaning that the markdown files get converted for every single request. I’m waiting for Geoffrey Grosenbach to finish his merb_static plugin. Once he will be done with the spidering, his plugin will automatically export the site as static HTML. The PDF version will be exported using a gem called UFO written by wycats. UFO is a JRuby bridge to Flying Saucer, an awesome Java library which can convert HTML to PDF.
As you can see if you browse the book, we don’t have a lot of content yet. However, you need to realize that we just started 3 days ago! That is what’s so amazing. People didn’t sit back and wait for some core team members to write the content. To the contrary, they have been submitting content and have already started the book translation into 10 languages:
I expect to receive the first Italian translations early next week and I was promised some Indian languages too.
Props to the entire community for putting its money where its mouth is!
- update_attributes regression fixed
- JRuby fixes
- perf boost
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)
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.
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:
- clone the book repo
- modify/add content
- rebase to avoid conflicts
- send me a pull request
- 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.
|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.
Yes, it is true and no, I am not being passive aggressive or cynical.
As you might have heard there has been some tension between the Rails team and the Merb team in the last few weeks. Sometimes caused by us, sometimes caused by them. I already addressed this issue in this blog post, so let’s move on.
Like most Rubyists, I use a mac and I often smile when I watch their ads. Then I see Microsoft’s response ad and I think … they don’t get it, I’m not a Mac, the dude on TV represents the Mac computer. I’m a human.
Thinking back to our community, I felt that it quickly became: ‘Hi, I’m a Rails developer’ and ‘Hi I’m a Merb developer’.
What started as a simple comparison to explain what the difference was between Merb and Rails quickly escalated into arguments about what framework is best and which one people should use.
I hear people in the Ruby community talking trash about Rails and criticize the Rails core team. I even saw people insulting DHH on IRC while he was not even on the channel.
I, myself, have to admit that I have been guilty of crossing the line a few times and have made some comments which can be considered as “bashing”.
I think now is a good time to apologize and to say that this kind of behavior is not appropriate.
After all, if we wanted to define ourselves as being “something” we probably should say: “Hi, I’m a Ruby developer”. Rails is not perfect, nor is Merb. I might disagree with some of the decisions made by the Rails core team but I still think Rails is a great framework and the Rails team has done an awesome job and deserves a lot of respect for its efforts. We are all part of the Ruby community and I think it’s time we all (starting by myself) act as a unified community.
Without further ado, here is my …
Top 10 reasons why we <3 Rails:
- Without Rails, the Ruby language would not be one of the top 10 programming languages
- Without Rails, we would still be writing thousand-line configuration files in XML to start your small app
- Without Rails, most developers would not know what MVC stands for
- Without Rails, I would not be a Ruby web developer
- Without Rails, we would not have Merb
- Without Rails, we would not have all the other cool Ruby frameworks
- Without Rails, testing would be something only the elite would do
- Without Rails, serving Ruby web apps would be a pain in the neck
- Without Rails, Zed Shaw would not be famous
- Without Matz, there would be no Ruby
- Without Ruby, there would be no Rails
Next time you think, I’m a Merb or I’m a Rails, think twice