Anthony Kelly wrote:
This looks pretty good. I saw the other thing on lighthouse: Overview - Narrative book (Getting Started with Rails) - railsdocs
Oops I meant:
It wasn't on lighthouse, that one never took off.
Yeah we moved all the book work over to the Basecamp. I think we're keeping the core work there and then we'll handle tickets, issues, and other input through Lighthouse.
We'll hopefully have some more information soon (we're hacking out an outline and such at present).
--Jeremy
Jeremy McAnally wrote:
Yeah we moved all the book work over to the Basecamp. I think we're keeping the core work there and then we'll handle tickets, issues, and other input through Lighthouse.
We'll hopefully have some more information soon (we're hacking out an outline and such at present).
--Jeremy
Oh, OK, awesome. Well, I'm sure that work would translate over pretty
easily if they did set up a core doc team. I know a lot of people
complain that obscure features can only be found on random blogs, and
that those don't ever get maintained. I'm kind of excited that there are
other people out there who would like to see rails documentation getting
maintained by the community. 
Anthony
The wiki has some places for users to look, though they aren't maintained. Would it be enough to update these and push for links to them from the front page?
So, say that Rails is to get an official documentation team. Whose decision would that be? DHH? Anyone in the core team? It would be nice with an opinion from the person/people that can actually decide wether or not to get an official team running.
I think the best way around this is just to do something cool and once you've done something, you seek to get that elevated to official status. Say you do an online book that's really great. That'd be wonderful and could well live under the rubyonrails.org site if it's awesome. The same with any other type of documentation, really.
That way we don't bestow "official" status to a group of people with good intentions who then never get around to actually doing the work (and at the same time discourage anyone else gunning for the same slot from getting to work).
This is especially prudent if this is to be a comparison to Rails Core. That group has its members picked from people who actually did something. Not from people who said they would do something. I think that's a good model to follow.
DHH wrote:
That way we don't bestow "official" status to a group of people with good intentions who then never get around to actually doing the work (and at the same time discourage anyone else gunning for the same slot from getting to work).
This is especially prudent if this is to be a comparison to Rails Core. That group has its members picked from people who actually did something. Not from people who said they would do something. I think that's a good model to follow.
This sounds very fair... Who's up for it? And what should 'it' be? railsbeginner.com? Neighborhood Watch for the wiki? Something else? Either way let's get organized. Suggestion for a name: 'Ruby on Rails: Documentation Taskforce'. Well, anyway, let's agree on one and then create at least a google group to get things together.
There is already a considerable group of us laboring on documentation. We have a Basecamp if you'd like access, and a mailing list (I think; if not, we need one).
That goes for anyone else also.
--Jeremy
I still have around $7,000 from the caboose doc project fundraiser to
support a decent effort to improve rails documentation. Now that we
are post 2.0 I think it is time again to find a worthy effort to fund.
Suggestions welcome!
There is currently a google group for ruby on rails documentation.
It's dormant. Feel free to contribute.
As a serial well-intentioned suggester, I strongly agree.
Courtenay wrote:
I still have around $7,000 from the caboose doc project fundraiser to support a decent effort to improve rails documentation. Now that we are post 2.0 I think it is time again to find a worthy effort to fund. Suggestions welcome!
Excellent!
There is currently a google group for ruby on rails documentation. It's dormant. Feel free to contribute.
OK. Do you have link. Let's use that. Also, anyone that can check over the RoR wiki and point out discrepancies/poorly written pages or better yet fix them will do a lot towards this effort.
Jeremy McAnally wrote:
There is already a considerable group of us laboring on documentation. We have a Basecamp if you'd like access, and a mailing list (I think; if not, we need one).
Can I get access to the Basecamp and the mailing list? Feel free to email me. Thanks.
I believe someone received/is working on getting a dump of the wiki to set it up somewhere on an anti-spammed, stable wiki package.
I'm not sure of the status of that...
I would suggest setting that up before doing any work on it; otherwise your edits will get overrun by spammers.
--Jeremy
Jeremy McAnally wrote:
I believe someone received/is working on getting a dump of the wiki to set it up somewhere on an anti-spammed, stable wiki package.
I'm not sure of the status of that...
Thanks for the heads up. Let me know if you hear anything
Anthony
Have you guys checked out http://articles.slicehost.com?
It was amazingly helpful in helping me get my server configured for rails. Why does that matter? Because I had no clue of how to do ANYTHING in linux before this. It basically held my hand through the most common tasks... and there was a chat where I could ask questions.
I would highly recommend using that format for the tutorials/documentation for rails.
Anthony Kelly wrote:
I received it... the status is, uh, I received it...
I can actually spend some time on it this week, especially if someone's there to crack the whip I mean remind me I mean help me test it.
Jay Levitt wrote:
I can actually spend some time on it this week, especially if someone's there to crack the whip I mean remind me I mean help me test it.
Ooh, ooh, Pick me.
Meh.. I'm not that impressed. For one thing, "Ubuntu LTS" is a designation, not a version. I have Ubuntu LTS on my server - it's Dapper. Which LTS are they talking about? For another, why is the main menu off to the right instead of in front of my face? I'm not saying it's awful, I'm just saying it's not an archetype.
The problem with *any* technical documentation is that every single reader has a different level of expertise. As you said, you "had no clue of how to do anything in Linux before this". If I had to read through that level of detail to set up Rails, I'd scream.
OTOH, writing multiple versions means there's more information you have to keep in sync as Rails changes - and more work, in general. Also, geeks suck at seeing things from the viewpoint of anyone less experienced than they are.
A good writer can balance all that out. So can a good editorial system (e.g. better wiki software, which we're working on, for some value of "we" and "working" and "on").
Jay Levitt wrote:
Meh.. I'm not that impressed. For one thing, "Ubuntu LTS" is a designation, not a version. I have Ubuntu LTS on my server - it's Dapper. Which LTS are they talking about? For another, why is the main menu off to the right instead of in front of my face? I'm not saying it's awful, I'm just saying it's not an archetype.
The problem with *any* technical documentation is that every single reader has a different level of expertise. As you said, you "had no clue of how to do anything in Linux before this". If I had to read through that level of detail to set up Rails, I'd scream.
OTOH, writing multiple versions means there's more information you have to keep in sync as Rails changes - and more work, in general. Also, geeks suck at seeing things from the viewpoint of anyone less experienced than they are.
A good writer can balance all that out. So can a good editorial system (e.g. better wiki software, which we're working on, for some value of "we" and "working" and "on").
There are always the 'beginner' sections of the wiki for the 'hand
holding' articles. I agree the the site design isn't amazing, but the
articles are quite good to help a novice. Besides, everyone is a n00b at
first 
And multiple documentation sources to bring up the need to update all of them, but it's also easier to find a documentation source you like if it's in lot's of different places. I'm excited to see better wiki software happening. Especially if there will be a preview option. It would be nice to have automatic redirects and standard ways of marking/categorizing articles.
Melvin Ram wrote:
It was amazingly helpful in helping me get my server configured for rails.
Do you use Apache and the mongrel cluster etc. on your Linux box? The Deployment HOWTO could definitely use some work once the wiki has been migrated.
A good writer can balance all that out. So can a good editorial system (e.g. better wiki software, which we're working on, for some value of "we" and "working" and "on").
And multiple documentation sources to bring up the need to update all of them, but it's also easier to find a documentation source you like if it's in lot's of different places. I'm excited to see better wiki software happening. Especially if there will be a preview option. It would be nice to have automatic redirects and standard ways of marking/categorizing articles.
Is there better wiki software happening? Url me please. 
Steven Soroka
Anyone who's interested, come join the group at
http://groups.google.com/groups/rewikify-rails
and be prepared to nag me!
