update on the documentation project
Courtenay : December 26th, 2006
Professional Author working on rails API
It seems like none of the published Ruby or Rails authors want to actually work on the Rails documentation. Perhaps its the lack of glory, or the fact that there are no residuals. I’ve spoken to most of the well-known, published, ruby or rails authors, and none of them are interested. I even hit up the Ruby guys at Rubyconf in person, and all of them said “Well, I don’t really know rails that much..” I’ve chased up the names: Hal, Chad, Amy, Lucas, Jake, Dave, Obie, David—even the guys who write the blogs and don’t have books out yet. They just don’t wanna do it.
So, the conundrum facing us today is, “Where do we find an author?” I’ve chased all the people I know. There are a few good projects out there worthy of mention; the fearoffish open-source rails book at http://svn.devjavu.com/rails/ is a prime example—but we need your help on this, now, folks. How do you catch a technical writer? How do you interest them?
RDOC project
The idea with this project is to make it simple to make patches to documentation, and to reward those who do. It’s Nearly Done, and the parts that work, work well. We really are fighting against the arcane rdoc format. But if you take a look at the commit logs it’s really just me plugging away. This doesn’t scale, since I don’t actually have that kind of time, and I’m not taking money from the master fund in order to work on it (that’s not what it’s for). Many people requested svn access, and then just didn’t do anything. Others started off strongly and then just disappeared, or have contributed two or three patches. So the app just stagnates, because there isn’t the interest.
What needs to be done?
- an automated way of posting patches to the core rails trac
- a fix for editing “class-level” code
- fix the “plea” code so that people can flag some docs as requiring attention
Sure, people donated so they didn’t have to worry about any of this. But that money is locked in limbo until we have a framework for handing out the cash to the masses (aka doc patches), and/or some decent technical writers willing to put in some time. And no, I will not look at proposals for all of the money to go to one writer. I also will not look at proposals from people who’ve never published a ruby technical document before.
Hook it up in the comments and let’s get the ball rolling. The wiki is at http://caboose.stikipad.com/documentation/
20 Responses to “update on the documentation project”
Sorry, comments are closed for this article.
December 26th, 2006 at 11:28 PM
I also will not look at proposals from people who’ve never published a ruby technical document before.
This is bit extreme, don’t you think?
December 26th, 2006 at 11:30 PM
This is why PHP will always be better! Better community support!
December 26th, 2006 at 11:36 PM
Distinguished authors refuse to write documentation for Rails… even if they’re gonna get paid for it?? I find it hard to believe.
Bryanl: I don’t find it extreme.
December 27th, 2006 at 12:22 AM
Bryanl: If you know Ruby and you’re a writer, you’ve published. Otherwise you’re just pretending to be a writer.
Mislav: please prove me wrong!
December 27th, 2006 at 12:40 AM
Have you tried getting publishers involved? I would think that the ideal model would be to follow the lead of “Version Control with Subversion”[1] and “The Django Book”[2]—a free book that is then published, for those who want a hard copy. In an idea world, the revenues from publishing the book would provide enough incentive to the authors (The Django Book is being written by the framework authors, for example).
[1] – http://svnbook.red-bean.com/ [2] – http://www.djangobook.com/
December 27th, 2006 at 01:07 AM
There might be a lack of enthusiasm because of the responsibilty involved. This project has received a lot of press (within the community) and it might be easy to be intimidated by the thought of a large group of donors scoping out what they’re doing at each stage.
Of course, it could just be that everyone’s busy, or that money doesn’t seem to be a good motivator in this community (as I found to my surprise recently).
Perhaps I will post about this over at Ruby Inside and see if that can interest those who, perhaps, have not heard of this project yet, as clearly the money needs to be used for something :)
December 27th, 2006 at 02:30 AM
As one of the guilty parties named in Courteney’s Roster O’ Shame, I feel like I should clarify my own lameness. The problem for me simply boils down to time, as in I don’t have enough of it, although the scrutiny of my peers might be also a bit of a disincentive as well I suppose (but I guess I’m not too afraid to make mistakes in public).
The scarceness here is not money (I get paid well enough I would do this for free), but attention, and anything you can do to help addled, over-committed authors like me to quickly write up docs for a certain section (the Plea proposal seems to be the best thing you can do here) seems like the best call (as well as any rcov-style metrics for tracking documentation coverage).
One other idea occurs to me. I don’t work in Rails in my day job, so any Rails dabbling is on my increasingly rare free time, but there are a lot of people/companies who consult as Rails developers. While you could pay them I suppose, it might be helpful to have an official Caboose Doc Contributor badge you could provide for people/companies who work on documentation. Get them the admiration of their peers or, more importantly, potential customers. Just an idea…
December 27th, 2006 at 04:59 AM
I was at a San Francisco Ruby Get together a few weeks back and someone presented a web app that would allow people to submit rdoc patches to core without the need to check out the source, create the patch, submit the patch, etc. It looked incredibly useful to help the community write the rdocs and the presenter said it was inspired/written during a recent ruby conference somewhere. However I’ve been unable to find it online at all. Anyone heard of it? I’d gladly contribute rdoc patches for free if there was an easy app as mentioned above to do it. Also, check out the postgresql docs. You can view them with or without user comments, so that’s another possibly simple way for the community to help improve the docs, or at least capture the gotchas for certain api’s
December 27th, 2006 at 05:28 AM
yeah that’s the app we were talking about.
December 27th, 2006 at 08:27 AM
Yes I imagine time is the main factor, as Jake said.
Still, a framework is only as good as it’s doco
December 27th, 2006 at 11:45 AM
court3nay: Is the app still live? I’ve come across it once or twice, but I don’t see it linked anywhere on this page. Where is it? Needs to be obvious.
December 27th, 2006 at 11:51 AM
court3nay: Is the RDOC app still live? I’ve come across it once or twice, but I don’t see it linked anywhere on this page. Where is it? If its like, it needs to be linked, big, bold and obvious, like the contributor list page. Probably from multiple sites. Maybe a big link badge for the site others could use to link to it as well?
Also, not that this is you, but isn’t their more than one of these http://railsmanual.com/ type sites where people can add comments? I could swear i’ve seen multiple, and they each have a few comments. Hmm, probably should just be ONE, like PHP.NET.
December 27th, 2006 at 11:52 AM
er “if its linked”, not “if its like”
December 27th, 2006 at 02:08 PM
If the documentation is going to be important and long lasting then I think it needs to be on official Rails site and like the PHP docs and be at. It needs to be the main link shown on this URL
http://rubyonrails.org/docs
December 27th, 2006 at 02:08 PM
If the documentation is going to be important and long lasting then I think it needs to be on official Rails site and like the PHP docs and be at. It needs to be the main link shown on this URL
http://rubyonrails.org/docs
December 27th, 2006 at 03:14 PM
“How do you catch a technical writer? How do you interest them?”
-later-“I also will not look at proposals from people who’ve never published a ruby technical document before.”
-and later still-“If you know Ruby and you’re a writer, you’ve published. Otherwise you’re just pretending to be a writer.”
There are plenty of technical writers, like me, who know Ruby, know Rails, and have published significant technical documentation and textbooks in other domains.
Ignoring published technical writers who haven’t written on Ruby, in particular, is probably your first problem. If you really want to get the biggest bang for the community’s buck, you may need to consider going outside your social circle.
December 28th, 2006 at 07:26 AM
I think we need to treat this as a project, so before we have a technical writer, we need a “project manager” so to speak. I don’t mean to sound all “corporaty” but If I were doing it, I would start with something like this:
Seems to me that it is more coordination of resources and constraints than the actual writing. Just my opinion. From the corporate experience, I find that documentation projects seem deceptively simple, yet they turn out to be almost as complicated and hairy as their technical/programming counterparts.
My personal O is that the money would be better spent on someone with organizational/technical writing skills rather than focusing on Ruby/Rails hotshots, because lets face it, they are too busy with work probably and the money collected is less than what a good programmer makes in a couple weeks or a month at the most.
December 28th, 2006 at 02:52 PM
I would imagine most of the published, well known Ruby writers are off writing books and blogs and don’t have time to heap on another project.
Perhaps you should lower your standards and have that person overseen by an experienced author(s).
December 30th, 2006 at 07:22 PM
Please choose a passionate and dedicated railer.
There is a job to do. It should be treated as just that. Who has applied? Absolutely nobody? If not, sum up the requirements and submit them to the mailing list. The docs are 85% for people learning the rails DSL and getting the hang of ruby – it could be best to have the first round of docs written not by a superstar, but by someone passionate about rails who recently went through the learning curve.
The community will be better served with decent docs soon rather than glistening, golden docs 1.5 years down the line. If round 1 is a success, the community will support a round 2.
The longer the wait, the more pressure will build, the less satisfied the community will be, and the more we will place hopes on having the holy grail of rails documentation.
Cheers!
January 3rd, 2007 at 01:53 AM
Has a plan of action been created for how this should all be done? I know you can say, rewrite the docs, but is there a format that has been decided upon, is there is specific design that needs to be adhered to?
I think the first thing that needs to be done, if it hasn’t already, is to set up the project and define how it will be laid out. Just as others have said, think of this as a Web Dev. Project. Do you have the XHTML/CSS wireframes for the presentation of the docs, a specified format that they must follow, etc.
An aspect that I feel is important, but often overlooked with technical docs, is that it needs to be presentable, easy to read, easy to find what you are looking for. It would be great if it had a pleasant design and presentation that is easy on the eyes.
I think if these things were already set, it would make it not so overwhelming to get involved in.