If I had to point one thing that gives me true headaches, I would certainly choose encodings. I have already spent a lot of time dealing with encoding problems and I usually get stressful when a have to deal with a new one (I think it is common sense to suppose that everyone would prefer spending time dealing with other things instead of encodings).
So, last week I was using irb and pry to prepare a small course about Ruby and I found out that I couldn’t input UTF-8 characters. When trying to insert a á I was getting this unicode character code:
After a quick glance in some search results for irb utf-8 problem, I discovered that I was having this problem due to a Ruby compilation without Readline (which is a library with some useful functions for command lines).
Fixing this was really simple due to the possibility of passing options to include on Ruby compilation on ruby-build. So it was only a matter of executing this line to recompile and reinstalling Ruby with Readline support.
This is a very opinionated blog post about why we should use Stack Overflow instead of mailing lists for open source support. This post doesn’t reflects the opinion of the company that I work for and I also didn’t receive any kind of benefit from Stack Exchange or its partners. As you may notice, I’m not an english native speaker, so if you find an gramatical or any error that may be related with a bad explanation, please provide some feedback in the commentaries. I will correct/explain better it as soon as I can.
In the past few months, I spent some time answering some questions about Devise on Stack Overflow and I found out that it is an awesome web application to ask and answer questions regarding open source projects (and everything else). I also try to follow some mailing lists of my favoured projects, but I realized how open source support works better on Stack Overflow than on Mailing Lists.
But why is it so famous? Well, It is not a simple Q & A website. Given a question and a answer, you can give a +1 to the answer if it is useful or a -1 otherwise. You can also accept an answer for a question you asked, that is, you believes that a given answer was correct or solved the problem that you had. You can also assign a tag to your question, and some people who follow that tag may be able to answer it. You can also attribute a bounty for questions users find relevant but hasn’t received any good answers (and this bounties are basically points, which I will explain later on this text). Besides this, you can comment on questions and answers to ask more information about it, without having to pollute the answers with this. Needless to say that if your question doesn’t fit with the question policy it will be closed without mercy.
It also doesn’t have a “Big Brother” team that moderates questions: all questions are moderated by the community. But not all members can moderate questions: when contributing with questions or answers you may receive points, and depending of the number of points that you have, you gain some trust and some “power” become available for you. In the beginning you can only ask and answer questions but after some points you can edit questions and answers, assign bounties, comment on questions or answer and even moderate questions and answers. You can also earn badges, based on goals. In summary, you earn trust and power through desert. Ask wise questions and provide great answers and you gain power. Promote or post spam, off-topic or flamewars and you will be banned.
Well, IMHO, I find it awesome. A lot of questions get answered in reward of points and badges that can make a lot of people (including recruiters) hear your name. This number of points, also appear besides your name on every question that you answer, which provides you more credibility. It is nothing more than a “gamificated” and improved internet forum that works.
But what about Mailing Lists? Mailing lists exists in a long time and became very popular with Yahoo groups and Google groups among other famous options. They’re very easy to use (just a matter of sending and replying to e-mails) but they do lack of a good search tool (it is not easy to find a question about something with only a naïve text field search) and usually have problems with off-topic discussions and , spam and flamewars. Ok, this is a human problem, but well moderated communities tend to have less problems with that matter. Also, e-mails aren’t a good place to discuss about code: the lack of a source code formatting turns very difficult to read it. The moderations is also difficult: you can’t remove an e-mail after it was received by the list, so irrelevant or off-topic questions may get more repudiating replies and attention than well founded questions about topics that really matter. Although they’re not great for support, they’re great to ask opinions and provide discussions and even announce new versions.
So, I’m not suggestions that we should stop using discussion lists. I’m only suggesting that we may reduce its scope to not accept (or accept and recommend posting it on Stack Overflow next time) support questions (some open source software already have two lists to avoid questions being asked on the development mailing list, which may be used for discussions about the development of the software, e.g. MongoDB-user and MongoDB development for support question), so it is only a matter of encourage users to send questions to Stack Overflow instead of posting on the support list.
To summarize, we have two options: one that seems to be outdated and its search only based on full-text search, without giving relevance to the content (as tags do), and not easily moderated. And another that provides support to source code formatting, tag assignment (and tags may have more relevance than words on a text) and that can be easily moderated. Other great advantage: we may sort the answers by the sum of all scores, so the answer that gets the biggest number of +1 (and is probably more useful than the others), will appear first. In contrast, there isn’t anyway to say that an answer solves your problem on a mailing list without having to send a message and the mail thread starts to get difficult to read.
So. here is an idea: why don’t we stop using it for support and only use it for discussion or announcements? OK, users may not like this at first and we may think about a smoothly transition, but in long term, we may have better resources to find questions and to follow a tag and answer questions about it.
What do you think about this? Would you use it for your open source project support?
As a Rails developer, I frequently have to check some definitions or get some help about a method or class on the api documentation. In my first months as a Rails developer, I used the official documention, but after some months I discovered other alternatives, which I preferred over the official documentation.
Some days before Rails 3.1 release, the official documentation was redesigned and it became so much better than it was, I liked the navigation sidebar, where you can find a method or a class easily. But (and this is IMHO) I still find it very unpleasant to read. However, as an official documentation, it is updated by the same time that the code is released and I expect it to have documentation for “edge-ish” Rails features (there is also a version which is synchronized with rails master branch).
Rails Searchable API Doc is the documentation I currently use when I develop Ruby on Rails applications. It has a nice look and also have the cool sidebar (by the way, the new design of Rails official documentation uses this engine, but with different colors). It also allows adding the Ruby language documentation and another popular libraries documentations as well. So, as a developer that most of the time uses Ruby, Rails, RSpec and Nokogiri, the possibility of adding this other documentations on the same window is great. Other cool option is the possibility of selecting the documentation for a minor version, so you can select the documentation for Rails 2.3.x, Ruby 1.8.x and Nokogiri 1.3.x. Besides this, we can download the full documentation (including generating a custom package of documentation) to access it locally (if you have a mac, you can use Fluid to setup an App with the documentation. Ok, you can do the same with the Rails documentation, but it is not easy as this. If you like this alternative and you also uses jQuery you can use a similar version to check the library’s documentation.
However, there is some points you should consider when using railsapi documentation: it is not updated as the official one (the current version is 3.1.3 but Rails api is still on 3.0.8rc1, one minor version behind). Other problem resulting of the possibility of adding many libraries, is that the results of a search can show you some irrelevant results, as you can see in the image above.
If you want to access enumerable#merge (which is probably the most popular between these results) you will have to look for results that aren’t what you want.
Api Dock
I used Api Dock a lot, but as I prefer an offline based version of a documentation, I choose Rails Searchable API Doc. But, there is some really nice reasons try Api Dock out.
First of all, it allows people to make comments to make the documentation more comprehensible (there is a nice example on has and belongs to many documentation) and it also allows other people to thank who wrote the commentary. Besides this, it gives you a nice look about a class/method among Rails versions, so you can see the point where something has been added or removed. It also lists some related methods whose documentation can be useful. It is also more updated than Rails Searchable API Doc, as of the time of writing this post, it is on version v3.1.0. It also shows the current status of the documentation, if it is extensive or there is only a few lines of explanation.
One shortcoming of Api Dock is that it is not open source, so you can’t generate it on your computer and access it locally, although it is free (as in free beer) to use. It is also only available for three projects: Ruby, Rails and RSpec and they can’t be accessed simultaneously (which can be bad if you like to see several documentations together but the search results doesn’t shows a lot of irrelevant results).
What about you? What documentation do you use? Have you tried these three I mentioned? Do you want to recommend me another documentation ?
