contents/articles/rails-doc-first-look.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 |
----- title: "Rails-Doc.org - A First Look" content-type: article timestamp: 1213853400 tags: "rails|ruby|writing|review" ----- <p>When you decided to learn Ruby on Rails (if you did, that is), chances are that you bought a book. I did, too, actually: there are a lot of very interesting and fairly comprehensive books out there after all.</p> <p>I actually never bought a book to learn <span class="caps">PHP</span>, in the past though. Why’s that? Well, for two simple reasons:</p> <ul> <li>The <a href="http://www.php.net/manual/en/"><span class="caps">PHP</span> manual</a> can easily be searched and provides enough documentation, in most cases.</li> <li>When the documentation is not enough, there’s always plenty of comments by experienced developers to save your day.</li> </ul> <p>That being said, <span class="caps">PHP</span> is still an awfully disorganized language, but believe it or not, coming from <span class="caps">PHP</span> I didn’t find <a href="http://api.rubyonrails.org/">Rails documentation</a> useful enough simply because it didn’t have these two simple but very powerful features. </p> <p>Sure, there’s the <a href="http://www.railsdocumentation.org/">Rails Documentation Project</a> which provides more organized docs, and <a href="http://www.noobkit.com/">Noobkit</a> does a nice job with its search-as-you-type feature… but still is not quite enough: you’d expect something much better than that for something like Rails!h3. Introducing Rails-Doc.org</p> <p style="float:right;"><img src="/images/railsdoc_logo_sm.png" alt="" /></p> <p><a href="http://www.rails-doc.org">Rails-Doc.org</a> focuses on providing a better interface to Rails documentation by offering two key features:</p> <ul> <li>A powerful, fast and useful document search</li> <li>The possibility to add notes to Rails documentation</li> </ul> <p>When the app went live, I immediately registered (it’s free of course) and started playing with it…</p> <h4>Search as you type…</h4> <p>The first thing I did was trying the search features, of course. I started typing “rout” for Routing, and I was immediately shown a list of matches:</p> <p><img src="/images/rails-doc_search.gif" alt="" /></p> <p>It took a small fraction of a second to load the matches, which makes me think that definitely they have all the names indexed somewhere. Nevertheless, it was a pleasant surprise: normally, these search-as-you-type utilities are not that refined!</p> <p>All you need to do is start typing at least three letters, and you get results, if any. <br /> if you press <span class="caps">ENTER</span>, you get automatically redirected to the first result. This can be good, but maybe it would have been nicer to load a “traditional” list of results, but it depends on your taste, really.</p> <h4>…or browse through the namespaces</h4> <p>Alternatively, it is possible to browse the docs in the more traditional way, i.e. according to their class or module: the <strong>Browse</strong> page does just that: it lists <em>all</em> Rails classes and modules, regardless of the nesting. But there’s more: a little roundy icon precedes each class name, to indicate whether the documentation is present, and to what degree:</p> <p><img src="/images/rails-doc_icons.gif" alt="" /></p> <p>This is an interesting concept: in this way, in theory, people should contribute to the documentation where it’s more needed.</p> <p>Each reference page is very neatly re-formatted: you can hardly imagine it’s actually the same content included in Rails’ RDoc pages!</p> <p><img src="/images/rails-doc_document.gif" alt="" /></p> <p>Finally, another nice addition is the <strong>Related</strong> column, which lists links to other items which are related to the current topic:</p> <p><img src="/images/rails-doc-related.gif" alt="" /></p> <h3>Contribute, contribute, contribute!</h3> <p>You have to register for something, don’t you? Yes. If you register, you can post notes to any document. Simple enough, all you have to do is to click the <strong>Add Note</strong> button and a form will slide down for you to fill in:</p> <p><img src="/images/rails-doc_note1.gif" alt="" /></p> <p>As you start typing, you’ll notice that a preview of the note is displayed instantly: as you can use SimpleMarkup to write notes, exactly like in RDoc, this feature can be very handy:</p> <p><img src="/images/rails-doc_note2.gif" alt="" /></p> <p>What if there’s no documentation for a particular class or method? You’ll get a warning like this one: </p> <p><img src="/images/rails-doc_nodoc.gif" alt="" /></p> <p>The idea behind this is that, if you provide some useful insights, they’ll eventually end up in Rails core documentation.</p> <h3>An Short Interview with Mikael Roos, from Nodeta</h3> <p>Before the application went live, I was lucky enough to get Mikael Roos to answer to some of my questions. Here’s the full interview…</p> <h4>What are you actually trying to do on Rails-Doc.org?</h4> <p>The initial goal of the project is to provide the existing documentation in a more accessible way, most importantly to provide a lightning fast search feature that gives weighted results based on the<br /> quality and amount of documentation. This we have already accomplished, and all remaining issues are related to browser compatibility. Another initial goal is to present a smooth interface for creating inline notes to<br /> the documentation so that Rails developers can post notes about certain methods etc. for themselves and others to draw knowledge from.</p> <p>Our longer-term goal (N.B. we are an agile project, so long-term means, say, three months) is to provide a way for the active members of the Rails community to improve the existing documentation based on the posted notes<br /> to create an extended documentation that could optimally even be made in to a patch and would find its way back into the actual Rails source.</p> <p>Another clear and obvious goal is to keep improving the service steadily as we progress toward the goals that I mentioned above.</p> <h4>Could you spend a few words on the “development process” followed by your company to develop this app? Did I read the word “Scrum” somewhere? Am I correct?</h4> <p>Yes, our development process of choice is Scrum. The core team is only three members, one backend developer, one backed/frontend develope and one frontend developer/UI specialist. I feel the team is optimal in many ways.<br /> The team also has a few more experienced developers who are primarily active in other projects to ask questions from, one of whom is also the acting product owner on the Rails-doc project (that’s me!).</p> <h4>Did you develop it in three months, or…?</h4> <p>The first release was developed in three <span class="caps">SPRINTS</span>, not months – so what I’m saying is the first release was developed in five weeks (first sprint was mostly introductory and lasted a week, the next two sprints, first<br /> development and then stabilization, were two weeks each). However, it is a <span class="caps">FIRST</span> <span class="caps">RELEASE</span>, which means the app is by all means not complete, but since we make software in a very agile way, it’a all about “Ship, ship, ship!”.</p> <h4>What is <a href="http://www.nodeta.fi">Nodeta</a>, exactly? My Finnish is a bit rusty nowadays…</h4> <p>Nodeta is a software development company that focuses on web software. We employ a highly agile and effective process. We have worked both on light independent projects and in the environment of large global enterprises.<br /> There are currently 10 Nodetans.</p> <p>Rails-Doc.org is a pilot project for your new shiny app, ApiDock. Is it an open source app?</p> <p>Unfortunately, I cannot go into details about APIdoc yet. What I can tell is that it is developed with Rails and that it won’t be open source, but rather it would optimally be offered as a service, which after all is what<br /> the word “app” on the web means these days. Open source projects could however use it for free, sort of in the spirit of GitHub.</p> <p>It will also most likely be separately targeted to larger companies.</p> <h4>Can you give me more technical details about the way keyword search is performed? Are you indexing/tagging documentation beforehand?</h4> <p>There will probably be a blog post on the <a href="http://blog.nodeta.fi">Nodeta blog</a> about the search and how it works after the first release comes out.</p> <h4>What about the social side of it: you’re hoping people will contribute with notes, which will then be collected and integrated in the documentation correct? Do you have any moderation or anti-spam precaution?</h4> <p>The quality of notes is judged in a social way. Notes can be thanked by other users and notes that get many thanks are showed in a more prominent way. Registration will be required in order to post notes and the registration will feature a captcha.</p> <h4>Will contributors be credited somehow? Who can contribute and at what level?</h4> <p>Anybody can post notes and good notes get thanks and thus so do their posters. Users that get lots of thanks will be later asked to become core users that can alter the extended documentation (not in the first<br /> release.)</p> <h4>You want to blow out competition and that you don’t want to fail: sounds a good plan! How is Rails-Docs different from other similar apps?</h4> <p>We think that our app is the first that is serious about making things happen. We think about users first and above all at this stage our search feature is frankly unparallelled.</p> <h4>Do you have DHH’s seal of approval? Will you? Is there any copyright issue with your domain name?</h4> <p>Time will tell what <span class="caps">DHH</span> thinks. We did contact him just a few days ago to ask what his thoughts about all this are and are waiting for his comments. I doubt there is any wrinkles with copyright as Rails-doc itself is a completely non-profit project.</p> <h4>What about doing something similar for the whole Ruby language? Ruby docs may also be easier, in a way…</h4> <p>It is possible that we might do just that but right now it’s all about Rails.</p> <h3>The Bottom Line</h3> <p>Rails-Doc.org is definitely an interesting project, which has all the potential to become a powerful, Rails-powered service. Sure, it’s not open source and this can be a bit of a letdown for some: but after all people flocked to GitHub when it opened, didn’t they?</p> <p>The search capabilities of Rails-Doc.org are definitely a very important step forward in making Rails documentation more accessible and easier to use, but the killer feature is definitely the possibility to add notes, if used wisely.</p> <p>I’ll be watching this project closely and I’ll pay particular attention on what happens to the community’s contributions: will it really be useful? Will it really help creating documentation patches to Rails core? Only time will tell, of course.</p> |