Posts Tagged book

If you already purchased an electronic copy (thank you!), go to your product page and download an update. Note that if you are on an iPhone or iPad and you click on the .epub link, the file will automatically load in iBooks, same thing if you have the kindle app installed and you are clicking on the .mobi file.

If you haven’t purchased an electronic version yet, you can still read the book in HTML format here. If you choose to do so, please still think about leaving a review on the O’Reilly site to show your support to myself and to my publisher.

What’s new in this update?

App built in chapter 2

I refactored the introduction to the book, you know have a new Chapter 2 which introduces you to GUI app development and lets you build a full app right away to give you an idea of what is available.

Chapter 3 covers more advanced concepts and was updated to reflect changes made on trunk.

The chapter on Core Data is now almost done, I will soon push an update with the end of the chapter, but between the chapter content and the example app, you should be good to go today.

GitHub repo with the code used in the book. (work in progress, I need to move more code there)

The book is now divided in two parts, one more theoretical and more practical. Even if part 2 isn’t written yet, the table of contents shows some of the examples I will cover. I hope to have some of these chapters written in a few weeks.

Lots of small fixes and updates thanks to the readers comments and to my editor.

App built in the Core Data chapter

Finally if you are interested in pre-ordering the book, Amazon runs a great deal on the book:

I started thinking about working on “MacRuby: The Definitive Guide” last year when I realized that the project had a great future but there was a serious lack of documentation. With the support of the MacRuby team, I worked on a table of contents and a pitch. The next step was to decide what we wanted to do with the book.

I know a lot of technical book authors and most of them will tell you the same thing: if you think that you are going to make money writing a book, you are wrong. Even if your book sells well, because of the time invested in writing the book, you are probably better off doing consulting work and charging by the hour.

So since day one, I knew that this project would not make me rich. The goal was to share knowledge not to reimburse my mortgage or save California from bankruptcy. While publishing a web book is great, distribution is quite limited, especially if you try to reach people outside of your network. That’s why I decided to start talking to a few publishers. Most publishers I talked to were interested in working on the book, however they were not really keen on publishing a Creative Commons Attribution-Noncommercial-No Derivative licensed book.

Let me explain why I think releasing technical books under a CC license is important. As you might know (or have figured out by now), I am not a native English speaker. I actually learned my first English words thanks to the computer my dad had at home. The problem when you don’t live in an English speaking country and you want to learn about the cutting edge technology is that you have to understand English. Thanks to the Internet, learning and practicing English is now much easier that it used to be. However, if you want to have access to books, most of the time you have to wait until someone translates the book and publishes it in your country or you have to manage to get an English version delivered to your country. This is often a pain because of national credit card limitations, international delivery restrictions etc… If you manage to find a way to get a copy, the book ends up costing a lot of money.

What does that mean in practice? Most of the technical books are first available in the English speaking western world, then slowly translated and/or distributed around the world. By the time you get a legal copy in Bolivia, Algeria or Vietnam, a new edition is probably out in the US probably because the technology evolved. Maybe that explains some of the book piracy worldwide?

Think about it for a minute: knowledge is power and time is money. And what do we do? We delay knowledge distribution. This is why I am a big fan of the Khan Academy and its awesome free online courses.

Turns out O’Reilly shares my vision and has already published a lot of books under various open licenses: http://oreilly.com/openbook/ I was also interested in publishing the content of my book ASAP so people could access it right away even though there would be lots of typos and missing content. This is also something O’Reilly has already done with the CouchDB and the Scala books.

Talking with Jan Lehnardt about his experience working with O’Reilly on the ‘CouchDB: The definitive guide’ book, I realized that we seem to have some shared interests. I contacted Jan’s editor and we decided to start working on the MacRuby book. The book will be available later on in all the usual commercial formats and I hope people will show their support so O’Reilly will be encouraged in their choice to continue publishing CC licensed book. At the end of the day, purchasing a CC licensed book helps supporting the authors, the publishers but also all the people who can’t have access to the latest technical books.

Finally, working on a book is not an easy thing, especially when you have to write it in a language that’s not yours. But I have to say that the community support has been amazing. Even John Gruber sent a fireball my way. And since the announcement was made, I have received a lot of comments, tweets, emails etc… It is very encouraging and it gives me the motivation needed to work on the book after a long work day.

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.

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.

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.