Merb, the frustration mounts
If you have read any of my posts, you will know that I am a fan of everything Merb stands for. This has not been without its moments of cursing, screaming and other tantrums. Modularity is a great thing and giving the choice to developers to pick and choose what components they want is a virtuous goal to try and achieve. Merb has aimed for this from the beginning, and many would argue it continues to meet it with each release. This has not been achieved without its fair share of sacrifices, the largest of which is documentation and support.
What makes Rails an excellent framework is the amazing amount of free support you get while using it. You can ask any other Rails developer how they solved a given problem and they can either give you an answer or refer you to somewhere you can find your answer. This is not the case with Merb. The modularity means that if I choose to use HAML or ERB with my application, I have potentially split the number of people I can ask for advice in half (if it were an even split). Now, if I was going to use another merb-more package that can potentially halve that list again and I am down to 25% community support.
Now much of this can be resolved through documentation. A good piece of documentation is more valuable than any amount of amateur advice given from community developers (the majority of development advice, is bad advice, but its better than none at all). This could potentially be the saving grace for Merb development, but documentation is incredibly lacking as well. If you take a quick glance at the Merb documentation, there is VERY little information on any of the methods and much of it is confusing to understand if it is there. What continues to amaze me is the lack of initiative to go back in and document the code for future releases. Instead it seems the focus is on features and improvements in speed. Merb is already faster than any other comparable Ruby framework, so let’s take a look at getting some documentation out the door so people can utilize the great features like slices. Luckily there is one initiative to develop a merb book, but it is unclear if this will be anything more than a collection of tutorials or a true reference book (let’s hope the latter).
Update – Due to user comments, I have spawned a new github community project called docmerb. For details, see my follow-up post.
December 10th, 2008 at 6:37 pm
I’m feeling the same way right now. I really love Merb, but I think it needs to grow before I use it for something big. I’ll keep using it for smaller projects that don’t require anything out of the norm.
December 10th, 2008 at 9:14 pm
I know exactly how you feel. I have been trying to use Merb for quite some time now. Every time I think about Merb, I get gitty, and I start dreaming about porting all of my apps over to it. The frustration for me mounts in two places for me. 1. When I update my gems and the application that was working yesterday now explodes into flames. I then have to go and track down dependencies on my system as I invent curse words unbeknown to man. 2. The documentation. I second your pain here. So many of the tutorials I have been able to find on the web so far are for older versions ( < 1.0 ) of Merb. I have bought as many beta books available for Merb in the hope that by cross referencing them I will find the answers I so desperately seek. Merb is the new kid on the block and has not had enough time for tons of great documentation resources to become available. Merb has fantastic momentum and I expect the documentation to catch up very soon.
December 10th, 2008 at 10:06 pm
I do agree that the documentation is lacking. It seems that Merb users (including me) are generally power users who know what they’re doing. However, i do believe more documentation will come as the framework gains popularity.
December 11th, 2008 at 12:08 am
Hey Jastin,
Thanks for your support and making an extra effort to let us know what you would like Merb to improve.
Regarding documentation, we’ve been working hard on getting more doc out there.
* Of course you have the wiki: http://wiki.merbivore.com/ which is pretty decent
* You have the book that you mentioned in your article: http://book.merbist.com for a preview (we have translators for 14 languages, all being part of the Ruby community).
* We have http://docsbeta.merbivore.com/ which is still an early beta but already let you browse the public API in context (only Merb core as of today)
* We have 2 beta books (The Merb way, Merb in action, and 2 others being written)
* We have a peepcode
* We have a Merb training organized by wycats and myself: http://merbclass.com
* We have an online class setup by http://rubylearning.org/class/
Regarding the Merb Book, you said: “it is unclear if this will be anything more than a collection of tutorials or a true reference book (let’s hope the latter).”
The answer is that it will be a reference book with some tutorials. My goal is to have cover the common questions people have about the framework and how to do things. We will obviously quickly explain the how and why . (here is an example of the “how”: http://book.merbist.com/getting-started/request-path)
Hopefully we will have a first version done in 2 or 3 months. We will then be able to export the book to PDF and distribute it for free in multiple languages. The static HTML version will also be available.
Once the initial release will be out the door, I’d like to focus on the more advanced topics and spend more time explaining the reasons behind things.
Regarding your comment about support, I’d like to say that’s why we came up with the concept of Merb stack. Most people will end up using the stack and most people will be able to help you without challenges.
To conclude, I’d like to thank everyone who’s been spending time working on Merb or using Merb. Documentation and Gem dependencies are the Core team’s top priorities. We decided to personally get involved with documentation and are working with the Rubygems maintainer to make gems even better. I would also encourage you to look at the spec suite which is also another great source of documentation as we are testing as much as we can through the entire stack, meaning that you can almost copy and paste the public spec implementations.
Thanks,
- Matt
p.s: Obviously your contribution to the documentation/book would be appreciated.
December 11th, 2008 at 12:48 am
[...] This project started to improve documentation coverage and clarity by establishing rules. After my last post, I figure this is something we should do for merb. Not only does this help the community, but it [...]
December 11th, 2008 at 10:31 am
One more thing. If you one of the Merb elite and want to share your expertise with a budding Merb community, we would love to have you review our course and make suggestions.
December 11th, 2008 at 12:28 pm
Rails suffered from these exact same problems in the very early days. I think most frameworks do. The problem is documentation sucks to write when there is all that fun code out there to play with, most developers aren’t focused on it. It takes a lot of effort from dedicated people to write good documentation. Hopefully as Merb gets more widespread more people will step up to the challenge and create some great documentation.
December 11th, 2008 at 2:44 pm
hmm I wrote a pretty lengthy reply yesterday but it never appeared on the site
It might be stuck in WP spam.
I was pointing you to various documentations such as http://book.merbist.com and http://docsbeta.merbivore.com/ both project being managed by the Merb team. I was also pointing out the few books we have as well as the fact that most people use the full stack and therefore you get a community of people knowing the same tools.
Finally, I was suggesting you help us fixing all these issues so other new people coming to the Merb won’t have to deal with the same problem you’re facing.
- Matt
February 18th, 2009 at 7:45 pm
Nice thoughts, but hey, cheer up! they’re going to be merged together soon: http://weblog.rubyonrails.org/2008/12/23/merb-gets-merged-into-rails-3
May 12th, 2009 at 6:25 am
I found this useful. thought I could share it with other wannabe merbists…
http://ghettochip.com/merb_internals