Fear of Fish
Don't be afraid, I work at Engine Yard, not a sushi bar.
Rails Documenting
February 14th, 2007
So, I start documenting for the Caboose Documentation Project on monday and wondered if anyone had any preference as to what I should document first? What's the most severely lacking part of the rails source code you think? If there aren't any suggestions I'll just be starting from the top and working down, alphabetically. Of course, as suggestions/requests come in I'll gladly divert from the stage I'm at if it warrants it.
Anyway, comments are appreciated. I'll give my full plan after the weekend, I have a Barcamp London 2 conference to attend.
Also, on a side note the caboose blog is back up.
33 Responses to “Rails Documenting”
Leave a Reply
Jamie van Dyke
Jamie van Dyke has been a Rails developer since the beginning of 2005, working with some of the major players in the web market. He also played a large part in the documenting of Rails for the Caboose Documentation Project and teaches others on his blog and in training sessions around the world. Jamie is a core Rails contributor, and the publisher of multiple gems and plugins.
I'm a father of 2, living in a little village called Skipton which is in North Yorkshire, England. Anything else you'd like to know you can ask. Check out my photo and info at the caboose facebook or my flickr page.
Jamie is also unsure why he must write a Bio in third person, and doesn't really have a fear of fish, he just dislikes the taste and smell of them.
Search
Recommended Services
Recommended Books
Congrats good sir!
I think ActiveRecord is what people have the hardest time grasping, and any additional examples and explanation that can be added there would be great help.
I'm not sure if this is something that falls under documentation, but I know that despite DHH going on about "Convention over Configuration", I am yet to find an actual definitive list of what those conventions are. I'd find that very useful.
Documentation for setting up the database.yml config for different databases would be nice.
I agree with zerohalo. Also the Prototype and Scriptaculous helpers need some documentation work I think. The current doc often referes to the scriptaculous wiki. But the code there is for Rails before v1.0.
Congratulations - you have some work ahead of you :) Robert is right; the conventions are not well explained. I would certainly like to see more examples to explain the concepts.
Examples, examples, examples.
API examples, normal use examples, tricky examples. We already have theory, API doc, ruby doc. But how does one USE any of this?
Thanks a lot for your work!
Creating new ActionView template handlers. If you can even figure out how they work, that is!
Also, the new autoloading/dependency stuff really needs a good write-up.
I don't know if this falls under the same category, but I was thinking it would be nice if there was a tool that could scan ruby source and tell how much "documentation coverage" there is. Sort of like rcov for docs.
It could scan the public interfaces, excluding anything with nodoc, and say which parts of the code are completley missing any documentation at all.
I'm all for adding extra examples, but I think if there is anything where there is no docs thats where I would start.
I'd also tell people submitting patches to run "rake doc:coverage" before and after the patch to make sure documentation coverage is maintained or increased, and never decreased.
I think a somewhat-replacement to Agile Web Development with Rails would be nice...
Most people just recommend that book, and "google this-that-etc." for alternatives...
It'd nice to have your documentation as to be recommended as a first look + guide + some reference to typical things to do with Rails. Then AWDWR + other books for "more advanced stuff".
It's rather weird that in 2007 (with Google, Wikipedia, and zillions of blogs and FOSS) we still "have to" buy a book just to learn a language (+ framework).
The new assertselect and assertselectrjs assertions are great, but it's unclear what can be done when passing them blocks. The resulting array of elements is made up of some sort of HTML tag objects that I haven't found documentation for. Also, the description doesn't mention the :chainedreplace option but uses it as an example without mentioning other chained RJS types.
It would be great to have more documentation on: multi-model edition (mainly examples), small but useful patterns/shortcuts/helpers (delegate, with_options, etc.), improved docs for AR filters. That's all I can think of for now.
By the way, you're working on something amazing :) Thanks for you work.
Proper and detailed documentation on caching techniques is something that is hardly available.
I'm glad this is finally happening, but I'm not sure "working down alphabetically" is the right way to go about it.
The problem with the current Rails documentation isn't that it doesn't have enough detail (it's often easy to just look at the code if you want to know more) but that it doesn't have enough big-picture content. The API documentation works as a reasonably good reference once you're up to speed, but the vital information about how everything actually fits together, what code should go in what places, how best to actually design and implement a Rails application etc is scattered over a thousand different blog posts and locked away in the paid-content Agile book.
Yes, there needs to be a centralised point where all of the Rails conventions are documented, with jumping-off points to find out how to override each one if necessary. There needs to be an authoritative demonstration of how to design, lay out, deploy and manage a Rails application, not longer descriptions of the ActiveRecord methods -- although, yes, some of this big-picture stuff would be extremely welcome down at the level of individual (but large and important) classes like ActiveRecord::Base, whose documentation is too large and fragmented to present any sort of coherent picture.
Of course there's a healthy variety of opinion about how best to architect a Rails application but this is just one more area where "opinionated documentation" would be a massive asset to people who are just starting out and don't have enough of a grasp on the technology to be able to make intelligent big-picture decisions yet: give them something solid and reliable to get them started, and they can always come back and rethink things once they've become more confident.
And then there's the obvious issue of how difficult it is to find documentation for methods that don't really exist in the Rails source, i.e. ones that are generated at runtime. These should be properly documented as though they were real methods.
Finally, the existing API ocumentation could be improved by an order of magnitude just by organising it properly; the rdoc-style output is utterly horrendous to use and to navigate, which probably puts many people off before they've even learned anything about Rails.
PS: it would be a mistake to take too seriously the various calls for documentation of relatively obscure parts of Rails. Anyone who is savvy enough to need help with configuring caching, for example, is probably also capable of either reading the source or asking for help. Of course it's important that all these things get documented eventually, but right now it's the fragmented, baffling and hard-to-find nature of the documentation of Rails' core functionality (i.e. blog posts, code snippets, IRC logs, Agile book) that prevents me recommending it to my lazier friends.
Just get all of the essentials sorted out, lower the barrier to entry (yes, plenty of examples, plenty of reassuring opinions, even if they're subjective) so that more people can actually start using the thing, and the more obscure bits will gather more eyeballs and become easier to document in turn.
Any new frameworks, especially this great as Rails is the practical stuff in documentation that matters. The basic documentation is a must and every method should have some documentation about usage, return values, exceptions, and some example of usage. The stuff that I would like to see is ActiveRecord, form helpers, AJAX stuff. This is a big and great project and it may require that all of us contribute as well. There is also a question about the gem documentation and general ruby documentation, but let do one step at the time
I second Tom's opinion in favor of big-picture content.
There are quite a few tutorials on the Web that will get you up and running with a sample application, and then there's the API documentation which will give you details about the available methods etc.
However, I miss everything in between: explanations of the design of Rails and the available concepts (Partials, Helpers, Callbacks, database conventions, Plug-ins, possibilities of methods like render or redirect_to and so on.
Secondly, an orderly overview of all available features would be nice, both inside Rails (e.g. the various Format and Tag helper methods) and outside (an orderly list of available gems or plugins for things like encryption, pagination or authentication). I know that the Wiki maintains a collection of plug-ins, but it's not structured enough and does not provide enough documentation about the features and differences between the various options to answer questions like "I need to do X, what libraries/gems/plug-ins are there, and should I use Y or Z for my requirements?"
REST and Routes would be fantastic.
I also second a big-picture doc... And don't know if you have any voice over this issue, but it would be nice to have something easier to navigate than current rdoc output, as someone has commented before.
Maybe once you start with the big picture you could release it and let people ask what are they more interested in.
Anyway this is just suggestions :-) Good luck!
I agree with a more booklike approach than an index approach. But the idea to restructure the API is a good one.
For instance, you could identify a lot of methods that users do not typically use and immediately make things clearer. Also, there is a lot of documentation in the API that doesn't get read, for example I only just noticed now that there is a whole section on Fixtures in there that is quite complete, but hard to find.
Just doing those two things would give a large benefit for relatively little work.
Hi Jamie,
Thought I'd drop you a quick note after your talk at Barcamp. Was very pleased to hear about this project and as I mentioned, I keep finding poorly documented areas. For now here's some specifics: 1) It'd be nice if the options that you can pass to the prototype library were a link to the prototype documentation - for example in the module ActionView::Helpers::PrototypeHelper 2) ActiveRecord could do with some reworking 3) http://caboo.se/doc/classes/CGI/Session/ActiveRecordStore.html is very poorly documented. It took us ages to work out how to override with out own session implementation. 4) Coming from Java land, I'm not a fan of the look and feel of the documentation - at times it feels cramped and lacking structure. That said, the option to view code is very cool.
Anyway thanks for a good talk and keep up the good work!
Cheers,
George
If our ShowMeDo.com can help through hosting freely-available video tutorials, just drop me a line (ian AT showmedo . com).
We're hosting a lot of Python tutorial content at the moment, we'll also be hosting a lot of tech material from the upcoming PyCon conference (including videos of the tutorial sessions). Included in that will be Django and TurboGears material. After PyCon this weekend we'll have served over 200,000 tutorial videos, but few for Ruby :-( Our Ruby section is rather sparse and we'd love to see it filled :-) Regards, Ian (co-founder of ShowMeDo)
Routing techniques are very scarcely documented, and could definitely use some love.
Including how to actually USE rails on a shared server or something equivalent that you don't have shell access to or don't have full admin access to get up new developers that just want to learn and aren't installing on a desktop.
Sweet! I know you want things to document, but I think the biggest thing missing is an easy to navigate and easily organized document structure. Maybe its just me, maybe I just haven't gotten used to the way RDoc is structured but I just find it cumbersome.
I've always liked the way PHP.net docs were laid out, how they have "related methods" somewhat and especially the examples/user comments. If I was to have one thing it would be some good example with extensive docs on the various "options" or arguments a given method has with a few examples of those.
I think that would be a great start. If you have a nicely implemented user feedback area for every page (protected against spam), I think the users will fill out the rest :-). Good luck and keep up the good work.
What about using a wiki for the documentation? Protect it against spam with by requiring login AND authorization to do edits. Be generous in the edit capabilities, and give it to anyone who submits a valid documentation patch.
I know when I look something up and its poorly documented, I'd be happy to update the docs after I figure out how it works. The key is to make it easy. I have no problem submitting patches for code, but it seems a bit like overkill to go through trac when I only have to fix one or two lines of docs. If I could do it inline within a wiki I'd be more likely to follow through.
The PHP documentation is ok, but I find alot of the user submitted code examples to be of very poor quality. I would rather NOT have user comments in the same manner. Instead focus people on updating the example code in the wiki.
You could generate a diff against the rails source every few weeks and patch up Rails. I assume for this project you've been given direct rails commit access, haven't you?
With Rails changing so quickly, I would find it very helpful to see at a glance what bits are current best practice. There is a risk that if nothing gets taken out of Rails (ok for backward compatibility), there are several ways of doing the same thing. It is difficult as a beginner, when looking through the documentation to know what to choose.
I am not sure if it should be a Wiki or piece of custom software, but I am sure that if the people blogging and discussing Rails in the Google group and irc find one autoritative place where all this stuff can be put together and (at least) one person coordinating this effort and building the foundations or guidelines for the documentation, the result could be equal to something like the RubyPedia.
It's currently hard (impossible?) to tell which API is 1.1 and which is 1.2 (or edge) only. I'd like to see more docs on the RESTful features I also like to see a different page layout for the API docs. I really don't care much about the "files" and "methods" frames, I always use the classes. It would be nice if I could have the whole left frame menu for "classes" and have the website remember that preference.
Examples, best practice, tips for us that aren't familiar with the theory behind building an application. I realize it may not belong here. But this is where I'd want to see it, using code I'm moderately familiar with and interested in.
+1 on routing techniques, autoloading/Dependencies
Also, plugin system needs in-depth docs, and ActionView helpers like Form/FormOptions need much love (docs there are somewhat complete, but low quality)
Maybe some stuff about basic database design? When to use constraints, what, if anything, should go into the database and what should stay in AR.
I'm a fairly new programmer. I like to the API. Whenever there is an example or more, it helps me immediately. Otherwise I struggle.
Also I think routes should be better explained.