I like GavinSinclair’s idea of the “UnderstandingRails” section, though I slightly favour calling the top node simply “Understanding”.
As I’ve mentioned elsewhere, what I think we need is a mesh of small pages linked together in multiple ways, so that users with different needs can all navigate successfully.
To that end, I am trying to do multiple things:
- Locate redundant information, and put it in one place (linked from the prior uses)
- Hierarchialize the new information I add, linking it in to existing structures (such as the Howtos—for instance:
The generic part of this was simple (see HowtoSetupApacheWithFastCGIAndRubyBindings). Since the PHP Nuke installation was only part of our site (and we are planning to use rails elsewhere) we also needed to learn HowtoDeployMoreThanOneRailsAppOnOneMachine.
in UsingRailsToGraduallyReplaceARunningPHPNukeInstallation,).
- Recognize and help formalize orthogonal structures, such as the Glossary or UnderstandingRails, and refer to their pages everywhere it is meaningful (e.g. write “PrettyURLs” rather than “pretty URLs” or “UnderstandingModels will help you see why we do it this way” instead of “this makes more sense if you understand how models work”)
In summary, I’d like to see:
- Glossary items listed on their page, and also linked to wherever the terms are used.
- Howtos listed on their page, and also linked to wherever the knowledge of how to do that task is assumed in a discussion.
- UnderstandingRails items listed on their page, and also linked to whenever an understanding of the topic in question is assumed.
- Authors? listed on their page, and also linked to whenever they are mentioned.
- …and so forth, if anyone has any other cogent ways of looking at the data (I’m not sure what they would be, but perhaps “History” or \ComaprisonWithOtherSystems or Rationales or…who knows.).
[Snipped some no-longer-relevant discussion.]
The UnderstandingRails page is coming along nicely now.
I’ve had a thought for another top-level category: Resources. It’s not a pretty word to fit into a page title (e.g. \ResourcesAvailableGenerators), but it’s a very important concept, so maybe someone can think of a better name.
The basic idea is this: people create useful resources to be used with Rails (generators, helpers, related libraries like “search”, etc.) and they get announced on the mailing list and that’s it. Someone starting with Rails a few months from now will have missed those announcements and will not know of such things. Of course, they can ask on IRC or the mailing list, but I think a Wiki category documenting the available third-party resources is a good idea.
At the moment, I’m adding “category: Resource” to any page I see which fits the bill — only one so far. If a number of such pages turn up, then a top-level “Resources” page (i.e. linked from the home page) might be justified.
There is an idea floating around (called “Boxcars” by some people) that I think needs to be fleshed out & run with. Basically, a BoxCar is a semi-standalone piece of a Rails Application—something like a module in other frameworks—that you can hook-in to your Rails Application and have it “just work”. The SearchGenerator or Authentication-stuff seems to fit the bill nicely. Instiki would probably be one of the largest “Boxcars” if made into one; most helpers would probably be too small to count. I think one of the first goals is to make them Gem-able.
I like the idea, but I’m on the border of over commited at the moment (just moved to a new country, learning a new language, have two pre-school kids, a full time job, am semi-active in several open source projects, and have commited to do quite a bit on this wiki…and I’m sure I’m forgetting something…)
But I do strongly support the idea of “Boxcars” and (to coin a phrase in the same vein) smaller “Ties” that you can just drop into your helpers directory.
— MarkusQI like the understanding section. For some reason it wasn’t linked on the main community page with howtos et al, so I added it.
— KevinClark?