content structure suggestion

[Matt Aimonetti]

Dana and I started working on a content structure suggestion.

I'd like to get started on planning for the work to do and create
small teams of people in charge of different sections.

Please review the document and share your view point.

Thanks,

- Matt

Click on http://groups.google.com/group/rubyonrails-wiki/web/content-structure-suggestion
- or copy & paste it into your browser's address bar if that doesn't
work.

[Brian Rose]

My only comment would be to flesh out the section on plugins upfront; it needs more structure.

One of the most difficult things to do when developing Rails applications is to find the right plugin for the job at hand. If we separate out the plugins into categories (i.e. Authentication, Search, Testing, Ecommerce, etc), it will make it much easier to find what you need. If we put some structure in place now, people adding new plugins are more likely to follow the standard and gardening will be less brutal after plugin authors have a go at it.

--
Brian Rose
br...@heimidal.net
http://www.heimidal.net

[Jeremy McAnally]

Hmm. Some of this stuff like testing seems like maybe it belongs in a
guide. Are you planning on something different going in there?

--Jeremy

--
http://jeremymcanally.com/
http://entp.com/
http://omgbloglol.com

My books:
http://manning.com/mcanally/
http://humblelittlerubybook.com/ (FREE!)

[Matt Aimonetti]

@brian  I edited the addon section as suggested

@Jeremy the guides only cover what comes with Rails and it does it in depth. The testing section would cover other plugins like context and bacon ;)
This section should also only give the readers a quick overview / get started type information, at least for now. Usually detailed information are available on the developers' sites.

- Matt

[Jeremy McAnally]

Ah that makes sense. I think this setup (shallow, quick pointers in
the wiki) is *exactly* what a wiki is meant for.

--Jeremy

[Dave Newton]

Brian Rose wrote:
> My only comment would be to flesh out the section on plugins upfront; it
> needs more structure.
>
> One of the most difficult things to do when developing Rails
> applications is to find the right plugin for the job at hand. If we
> separate out the plugins into categories (i.e. Authentication, Search,
> Testing, Ecommerce, etc),

I'd suggest heavily-gardened (or even "official") tags. Plugins are very
hard to find as things are now, as they're differentiated only by view,
controller, DB, etc. The tagging on agilewebdevelopment.com, of course,
is completely useless, but it doesn't *need* to be.

I'd also suggest adding some date/activity information :/

Dave

[Matt Aimonetti]

I'm not sure we need tagging right away, if we stick to categories as suggested by Brian we should be fine. Plus, the search engine should be able to easily find content for you.

What do you mean by "adding some date/activity information"?

- Matt

[Mike Gunderloy]

As one of the Guides editors, perhaps I can chime in here. I don't
think we need to segregate material such that there is no overlap
between the wiki and the Guides (or between either of them and other
documentation efforts such as the RDoc and the coming Rails Book). I
think as we flesh out the Rails documentation story, we will end up
with things covered in multiple places, with different emphasis and
depth, and cross-references. The overall goal should be to make sure
that, no matter how they come into the community, people seeking
useful information can find it. I'd rather have overlap then have
someone unable to get their questions answered.

Mike

[Dave Newton]

Matt Aimonetti wrote:
> I'm not sure we need tagging right away, if we stick to categories as
> suggested by Brian we should be fine. Plus, the search engine should be
> able to easily find content for you.
>
> What do you mean by "adding some date/activity information"?

Adding date/activity information for plugins (and automated URL checks).

The sheer quantity and completely unknown nature of the plugins listed
on agilewebdevelopment.com is frustrating and not a good experience, let
alone for a new RoR developer. Is the plugin actively developed? Release
info? URL that actually works? You know the drill.

I'm reticent about coming up with an initial list of plugin categories;
static lists like that are almost never adequate, although providing the
ability to belong to multiple categories might alleviate that concern
(somewhat).

Dave

[Brian Rose]

Imo, the plugin authors should be updating the wiki with latest version, doc URL, etc. We should just have to setup categories for them and they'll take it from there.

(I know that sounds like a pipe dream, but an authoritative wiki that's well maintained can easily function in some fashion as a plugin dev's marketing tool, and they'll want to keep it up to date.)

As for categorization, most plugins fall into one concrete category so long as our categories are broad. Few will fall into more than one. (I can't think of any examples right now.) This being RoR, we should stick to the tenets established in the community and build the wiki something for the 90%.

[Matt Aimonetti]

I agree Mike, however as we start with the content, I'd prefer to start covering content that's not yet available in the book. You're right to mention that we shouldn't avoid content, just because it's already covered in the guides.

- Matt

[Ted Han]

No way. We should not expect plugin authors to take responsibility
for their entries on someone else's wiki. Ideally you could just pull
content from their site (pipe dream). A more realistic example would
be to keep as general as possible about plugins and link appropriately
to relevant examples.

The real problem here is that not all plugin authors are equally
invested in the tools they have created. Some of them barely have
time to maintain their plugins. I would absolutely discount the
likelihood that people'll will keep up on this.

What would be good would be a mechanism for reporting when info is out
of date on the site to have someone investigate. A mark and sweep
algorithm one might say. ;)

==============================

More broadly i'm trying to write up a discussion piece on guidelines
for the wiki. What it is that we have to work with, and what sort of
things we should keep in mind while directing people as to how they
can help out.

Yours typing hastily,

-Ted

[Matt Aimonetti]

Ted, could you please start a new thread about wiki guidelines please?

- Matt

[Brian Rose]

I think I may have overstated my expectations of plugin authors. ;)

What I mean is that we will be responsible for putting together a structure that future editors will follow. However, we do not want to be responsible for checking and re-checking the version numbers, release dates, and URLs of every last plugin posted. There are simply too many.

If we play our cards right and make the plugin section very simple and well-organized (read: concrete over folksonomic), there is a better chance of other people adding and correcting imformation per the standard already set.

On Wed, Jan 14, 2009 at 5:08 PM, Ted Han <noth...@gmail.com> wrote:

[Ted Han]

See this is where having widgets in a wiki might be useful.

Being able to tie examples to a specific version, and have the wiki be
smart enough to know what the current version of a gem is (which would
be doable, since rubyforge is queryable), and automatically link to
the newer version of a gem, or at the very least, indicate that an
example was now out of date w/ the most recent gem version, would be
extremely handy.

-T

Matt: Yep, will do.

[Matt Aimonetti]

ted: it sounds good but overly complicated :p simpler is better ;)

- Matt

[chris [at] thewebfellas.com]

any objections to me adding a nginx+thin article to the deployment
section?

[Matt Aimonetti]

no objections at all, that's actually a great idea.

Thanks,

- Matt

[chris [at] thewebfellas.com]

great - added a page and populated it (i've posted a thread for
comments and feedback)

i'm also happy to pick off the nginx + mongrel page if you'd like..

[Matt Aimonetti]

Absolutely :) the more up to date content, the better.

Thanks a lot.

- Matt

[tomkarlo]

I know there's going to be a few reasonably valid objections to this,
but I think we may need to think about editing plugin lists that are
to some degree a filtered selection of just the plugins that have
reasonably wide adoption and are actively maintained (we could also
list new, but not widely adopted, plugins seperately or just note that
status.)

Gems and plugins are one of the best parts of RoR. They're also one of
the most frustrating, because finding them, even for a basic issue
like authentication, is a big chore. Most people want to use a plugin
that's reasonably widely used (both so it's been tested, and so that
it's likely to stay active.)... even for basic concepts like
authentication, flagging and attachments that can be a pain to track
down.

Maybe we have a page on say, authentication packages, with an overview
of the subject (common features, issues, etc.) and then a brief set of
summaries of the most common choices (e.g. authlogic,
acts_as_authenticated, etc) that is not represented as exhaustive. But
for someone starting from zero it will provide a lot of help, since
for a new RoR user, the most common packages are probably going to
satisfy their needs anyway.

Below that, a bullet list of current and past authentication projects
that's as complete as possible (but easy to maintain, and anyone can
add their own project on the list in seconds) and finally, some links
to search the common repositories for projects of that type (e.g. a
search of github for "authentication")

Having a content pattern like this for plugins would encourage
developers, especially new ones, to use the wiki as a starting place
for their search when they have a common plugin/gem type need, but not
require continual updating and revision of the content.

Tom

[Kosmas]

Can we add another section in the Rails plugins called maybe Misc
that we hold anything that doesn't fit in any of the existing
subheadings?

I'm actually thinking about ActiveScaffold, geokit and ym4r_gm ?

Objections, anyone?

[tomkarlo]

How about a Geolocation category for geokit and ym4r_gm? Neither
package's name makes it totally obvious what they're used for and
geolocation will be something a lot of folks will be looking to do.

[Dana Jones]

Plus a Miscellaneous section this early in the game is very tempting,
and I would be afraid would become an all-purpose dumping ground.

Dana

[Kosmas]

Valid suggestions, so I've added two new categories (Scaffolding,
Geolocation), and added the ActiveScaffold,Geokit and YM4R/GM plugins.