So the short week after the vacation is now over. It took a little bit of time to get back up to speed with our work. We actually forgot some of the things we had done before the vacation. We remembered that we had fixed a failing test before the vacation but somehow it was broken again, so it took us a while to figure it out since we didn’t remember how we had done it before. After that we were back on track though, and I think it won’t take long until we will be done with the locals problem. It will be interesting to see if our solution will truly work and what Matthew and others will think about it. We actually had some questions for Matthew this week but he wasn’t on campfire at the same time as we were, I hope next week we will be luckier. This week we also had a retrospective with our team. It seems that the team is working quite nicely, everyone had a hard time coming up with negative things that could be improved upon. One was the division of tasks, but that was mostly due to the nature of the task at hand, it can’t be easily divided.

This weeks topic will be the documentation of Ruby on Rails.

The guide

I’ve probably mentioned before that Ruby on Rails has a guide. This is the primary documentation for Ruby on Rails, and it covers most of what you can do with Rails and how you can do it. The guide is maintained by the community like the rest of the project. For me it was and is very helpful when learning to build things with Rails, and overall I think the quality of the guide is quite good. It also has some parts that go into the details of how some part of Rails works, like the Rails initialization process. This part of the guide is lacking though. I believe it would be useful to have more guides about the internal workings of Rails to help people get started on contributing. Of course this would require a lot of hard and maybe boring work. Since different parts of Rails are written by different people, the one making a guide about the internals of Rails would need to try to read and understand a lot of code written by other people. I understand if there aren’t many people willing to take on that task.

The rest

Code comments, the API and short explanations on the github pages are the rest of the documentation that Ruby on Rails has. For example Active Model has an explanation about what it is on github. Similar explanations exist for most parts of Rails. It’s not much, and I think this could be a good place to add something more. Since The Rails Guides is mostly about how to do things with Rails, Github could be a good place to write about how Rails and its different parts work.

The last part of Rails documentation are the comments. This part of documentation varies a lot, which is expected in an open source project. Some parts have great comments. Here’s an example of a file that has great commenting. Most files don’t have those kinds of comments though, so this is another area that could be improved upon.

Overall, I think the documentation of Ruby on Rails is great when you want to learn how to build things with it, but is lacking when you want to learn how things work. Code comments are probably the easiest place to improve on, you could just emphasize it more in the contribution guide and pull request comments. But what I think would be more helpful is a real guide on how things inside Rails work, it would make contributing much more easier. For me it took a lot of time in the beginning to start understanding some parts of the things I needed to understand. A guide would have made it a lot easier, but it’s a lot of work to create a guide like that.