Table of Contents causes students to clobber RailsInstaller with manual install

[nuclearsandwich]

Continuing from my "buried lede" in #247 the past three installfests that I participated in, which I regret to say were all last Spring, I noticed at least a handful of students on Mac OS X who were following the Installfest instructions independently and successfully installed Rails via RailsInstaller proceeded by then following the Mac OS X Lion steps.

When talking to each of them the reason they continued was that they saw Mac OS X Lion in the table of contents and thought:

When @alexch and I originally talked about the table of contents, the hope was that it would provide an anchor that made orienting both students and mentors as they went through the curriculum. I'm not entirely certain that it accomplishes that goal, but I've seen it actively do the opposite on multiple occasions in the installfest and I think we should turn it off.

[nuclearsandwich]

/cc @lilliealbert

[lilliealbert]

Jumping straight to murdering the TOC seems a bit ... nuclear, @nuclearsandwich.

I think there are probably other options. Maybe we can find one.

[nuclearsandwich]

What if the table of contents was hidden by default regardless of screen size?

[tjgrathwell]

How about we prune parts of the subtree that aren't relevant to the current page?

For instance, the outermost layer could only show the first level of depth:

...and the inner levels would show a focused view with just the current subtree (parents and all children) visible

This still means when you select 'Macintosh" you get the full subtree of pages displayed underneath

But we could also choose to only show the top level of any child pages that were "siblings" (like the OS pages are)

This all seems pretty attainable to me by tweaking the existing code. We could also have pruned subpages still appear in the DOM but as 'hidden', to facilitate a "show everything!!!" button (maybe only for developing).

[nuclearsandwich]

In other folks' observation. Has the table of contents ever actually helped? I think there's some potential in the subtree stuff but from what I've seen it might be work that saves a feature that didn't turn out to be super useful in the first place.

[nuclearsandwich]

We definitely shouldn't do this as seeing Mac OS X Lion is what befuddled the users on whose behalf I opened this issue.

[tjgrathwell]

It would be good to get perspective from more students and teachers for the "is this actually useful" question. I only know that the TOC is incredibly useful to me as a TA in orienting myself regarding a student's current progress and helping them jump around to previous sections they might need to repeat.

The co-presence of "OSX Railsinstaller" and "OSX Lion" in the last screenshot is supposed to be abated by the fact that as soon as you choose one, the other will no longer be present.

The other-other pruning option is to never show ANY sub-pages of the current page on the TOC, which I think is a bit over cautious. I would definitely still want there to be a 'Show all navigation' option to enable fast page-switchery by a TA.

As a side issue, if doing the "OSX Railsinstaller" instructions followed by "OSX Lion" (RVM) breaks someone's Ruby, that's very bad news, because that should be a supported pathway. I would hope that someone who uses Railsinstaller to install 1.9.3 can peacefully use RVM to install 2.0.0 later on.

[tjgrathwell]

Lillie closed this because she was OVERZEALOUS. It is still open.

[alexch]

Maybe the solution to Steven!'s woes is to put a sidebar link back to
Railsinstaller at the top of the Lion page.

[ [Railsinstaller] should work on Lion, and it's pretty easy to use. [Click
here] for instructions. ](Put another way, it's not really the TOC's fault that we have 2 mutually
exclusive ways to install on Lion...)

[mehulkar]

I think we can do two things to make it easier to follow the hierarchy:

1. Add expand arrows to the sides of the menu items. This will be easier to follow than whitespace, IMO.
2. Add an .active class to the current top level menu item for visual separation from the other top level menu items. Case in point: the Ember.js guides minus the fancy expand/collapse animations.

[tjgrathwell]

I did some surgery to the installfest over the thanksgiving break and the TOC now looks like this:

and here when fully expanded

So it's a lot slimmer in general, navigation-wise, which might help.

We could also try folding the 'Install Xcode' step into 'OSX RVM' and likewise folding all the windows-specific stuff into 'Windows'.

It's unlikely here that someone will move on from 'OSX' to 'Windows', but maybe still possible that someone would go from 'RVM' to 'Railsinstaller', so it may merit hiding or greying out the other "options" on the same level as the current page.