Anyone know why the Rails Guides have extremely few hyperlinks to reference material? The Guides are my main go-to doc now because they’re targeted so well at the app developer audience. But it’s difficult to go from there to deeper material in the API. Is this an intentional design decision?
Would there be an objection to hyperlinking class names to their API?
What about creating an appendix per guide of links to the API for mentioned classes and methods?
Why did you ask this question twice?
@Robb - I agree with your question.
It would be helpful to link to Rails docs more often. I especially like the appendex idea. Do you have ideas for how to implement an Appendix?
It would help ensure old RailsGuides are still valid for new Rails versions since authors could compare RailsGuides links with Rails changes. (IE, Rails feature A is linked in RailsGuides 1, 2, 3. Rails feature A changed in Rails 4. Therefore, need to verify Rails Guides for 1, 2, and 3 are still valid). How can I link to a specific version of Rails Docs?
Linking would be nice.
Indeed, one of the ideas of the guides is that they are top-down/how-to oriented, but are not references. So in general it would be awesome to say: this is how you define and use a has_many, and these are the three most often used options, check the API for the other dozen (linked)". There is no reason this is not actually that way, it is just that nobody did it.
It has to be done with a good taste and balance though, I think it would need some experimentation to see how it would look if applied as a convention throughout the guides. Whatever solution would need to be implemented in a coherent manner.
I mean, it’s something that would impact the guides as a whole and would need to be seen from that global perspective.
It should be done in a way that generates edge or stable links depending on the docs set we are generating.
If you’d like to work on this it would be awesome. I’d only wait a few days, Prem is converting everything to Markdown and merging would not translate the work to the new files.
If you’d like to work on this it would be awesome. I’d only wait a few days, Prem is converting everything to Markdown and merging would not translate the work to the new files.
YESSSSSSSSSSSSSSS! This brings me great joy. Why is this happening, though?
:).
It was Prem’s initiative. CHANGELOGs are written in Markdown and we have the feeling that most Rubyists use Markdown, you don’t hear Textile very often in our community. In practice it is no big deal because you take a cheat sheet and this is not precisely LaTeX ;), but you cannot deny Markdown will sound less foreign to guide authors and contributors.
Cost/benefit is not clear depending on how you see it, but Prem wanted to do it so green light!
Sweet 
Thanks Prem!