News from the Documentation Front
Posted by fxn June 02, 2011 @ 08:47 PM
New Configuration Guide
Rails 3.1 will come with a new comprehensive guide about configuring Rails applications written by Ryan Bigg (@ryanbigg). The current draft is already available in the edge guides.
Rails Documentation Team
The documentation team, which was created some three years ago and consisted of Pratik Naik (@lifo), Mike Gunderloy (@MikeG1), and me, played a key role at bootstrapping docrails. Together with lots of API contributors and guides authors. Kudos to Pratik and Mike, their effort was outstanding and gave a definitive push to this aspect of the project.
After all these years, documentation maintenance happens regularly in master. Because of that, we are no longer going to have a separate documentation team. The same way we do not have a separate testing team. Tests and docs are an integral part of Ruby on Rails and complete patches have or should have proper tests and docs coverage.
Rails Guides Reviewers
Reviewing guides needs a special profile and dedication that has its own standards and pace. There's going to be a team of guides reviewers that will take care of new material. I am very glad to announce that Vijay Dev (@vijay_dev) is going to be the first member of this team. Vijay has done an awesome work in docrails in the last months. Welcome aboard :).
Next Steps
The Rails documentation has improved a lot in the last years, it has more content, and it has better editorial quality. But there's still a lot to do. Here are some ideas to work on:
A new documentation generator that evaluates the source tree and introspects to generate the API, mixed with a parser to extract documentation snippets.
Methods in the API have a link that toggles the visibility of their source code. Wouldn't it be awesome if there was a toggler that disclosed their tests?
Test coverage for the guides.
What about a gorgeus template design?
If you'd like to hack on any of them please go ahead!
Sounds great. One thing I miss about PHP is commenting in the php.net docs – any chance we could have something like that please?
@AstonJ: check http://apidock.com/rails
Zimozimo – I’ve seen that, but it would be better if the official docs had commenting, as they will be the first port of call for most people.
Also, while I’m at it… could we have a forum too please? :D
Please tell me you are expanding on yard or rdoc or something existing instead of creating yet another way to generate automated Ruby docs ;-)
@AstonJ: There’s the YARD version of the Rails docs which has commenting and all the nice things: http://rdoc.info/github/rails/rails/master/frames
Regarding the API generation tool, it may be based on YARD or RDoc. Indeed it would be better if we could hook into a standard existing tool.
Point is, in Rails there’s a lot of stuff that happens dynamically when class definitions are executed. Like running included hooks. Because of that, the ancestor chain of classes can’t be computed with a parser, and thus the API of key classes like AR::Base is very incomplete.
Regarding comments, though I am not closed, I am not either a big fan of them. There are new Rails versions often and I am worried about the maintenance of the comments. If we wipe them out, there’s little point in practice in my view. So, not very excited about this, though if someone wants to propose something I’d take it into account.
Additionally, I’d like the documentation to be a static website as much as possible.
I really miss a search feature, and documentation about dynamically generated methods like before_filter.
It would be great to be able to type posts_url and being automatically redirected to rails routing documentation.
Having an official, integrated YARD-powered documentation site would be hugely beneficial. I stopped using http://api.rubyonrails.org/, as http://rubydoc.info and YARD emerged as better tools.
As far as I know, YARD can be extended to fit into a custom layout and template, allowing for tight integration with the rest of the Rails web site. Furthermore, custom behavior can be implemented for stuff like `before_filter`, allowing for better documentation.
May I also suggest that a complete redesign/update of http://rubyonrails.org be considered?
Daniel