Rails is well documented in its API, but there’s “The ‘Middle’ Documentation Problem” where many newbies don’t quite get how it all fits together. This is partially because Rails has so many features, and partly because it’s so easy … once you get it.

To help people understand the different aspects of Rails, write a page called “UnderstandingSomethingOrOther”, link to it here, and give it a category of “Understanding”. UnderstandingModels, UnderstandingViews, and UnderstandingControllers should give a good example. Don’t explain how to do something in these pages; link to a Howtos page instead.

List of “Understanding” Pages

The tools behind rails

• UnderstandingRuby (and UnderstandingVariableLifetimes for variable scopes)
• UnderstandingRegularExpressions
• UnderstandingAjax

The developer’s perspective

• Understanding Rails conventions (over configuration). E.g.:
  • When to use/expect plural or singular
  • Convention-solved things, like many-to-many models
  • Capitalisation
  • Prefixes/suffixes (xxxController)
  • Etc, everything related to that.
• UnderstandingMVC
• UnderstandingWebApplications
• UnderstandingRailsMVC
  • UnderstandingModels
  • UnderstandingViews
  • UnderstandingControllers
• UnderstandingDevTestProduction (aka UnderstandingEnvironments)
• UnderstandingWhatFilesGoesWhere—an overview of the Rails directory structure.
• UnderstandingWhatMethodsGoWhere (or “where to put the method you want to write”)
• UnderstandingWebPageBreakdownIntoRailsPieces?
• WhenToUseTheModelMethod
• UnderstandingTheScriptFiles

A transaction’s perspective

• UnderstandingHowRequestsAreRouted
• UnderstandingHowPagesAreRendered?
• UnderstandingHowStateIsMaintained
• UnderstandingRequestParameters
• UnderstandingDefaultFileUsage (WIP)

The user’s perspective

...

Rails components

• UnderstandingPartials (needs work)
• UnderstandingHelpers
• UnderstandingComponents (needs work)
• UnderstandingGenerators
• UnderstandingValidation (not really a ‘component’ per se, but where else would this belong?)
• UnderstandingMigrations
• UnderstandingSessions
• UnderstandingRake? (not started)
• UnderstandingAggregation
• UnderstandingPolymorphicAssociations
• UnderstandingWebService? (not started)
• ...

About This Page

Is this “understanding” concept a good strategy for organising the Wiki? Air your views in UnderstandingRailsDiscussion.

category: Understanding