Update Wiki

[orenyk]

We need to overhaul the Reservations wiki. The wiki should include three distinct sections - one for users, one for administrators, and one for developers.

• User Section: The user section should walk end users (both regular patrons and checkout persons) through the basic tasks of using the app. These include but aren't restricted to:
  • creating a user account
  • browsing the catalog
  • selecting an item to reserve
  • changing reservation dates
  • creating a reservation
  • common reservation issues
  • checking out equipment
  • checking in equipment
  • reporting issues / giving feedback
• Admin Section: The admin section should be geared towards administrators of Reservations instance and should include:
  • installation / deployment of the app (including security / authentication setup)
  • initial setup of application
  • catalog management
  • user management
  • reporting
  • application settings
  • blackout dates
• Dev Section: The dev section should be geared towards developers looking to contribute to Reservations and should include:
  • requirements
  • local installation (including Ruby / Rails and database setup)
  • git branching conventions (e.g. naming, git-flow, etc)
  • version numbering info
  • issue labeling conventions
  • milestone conventions
  • changelog conventions
  • descriptions of 3rd party tools / libraries that we use and how we use them along with any other usage notes (see existing pages and this template page)
• The wiki should be well organized and easy to navigate. For examples / inspiration see here
• All existing pages should be either included in the new wiki or placed in an archive (delete nothing... for now)

NOTE: Any potential bugs / features that come up during the wiki overhaul, particularly during the user and admin sections, should also be added as GitHub issues.

[orenyk]

I've added pages for Changelog guidance and a basic development workflow; they definitely need to be polished and expanded :-)

[shippy]

We currently have three sources of information. The README.md file associated with origin/master and origin/development; the wiki; and the github.io page.

Here's what I propose:

• README.md should be geared towards webmasters who will be setting up the project, both in terms of why they should choose Reservations and how to set it up;
• the wiki should contain all the dev things and only the dev things;
• the github.io page should be geared towards users, differentiating between Admins, Checkout Persons (or Officers -- the people who are employed to facilitate the day-to-day usage of the system) and the end-users (or Patrons -- just the people who use the system to check something out for themselves).

[jasonkliu]

I'm looking at Shifts right now, and updating the gh-pages branch using Jekyll. The Shifts wiki currently has no content, so it also needs a similar overhaul.
I agree with the methodology proposed by @shippy in the above comment regarding the separation of different pages. We should have a large link on the github.io page to the wiki.

Are we planning on making yalestc.github.io a fully functional website, such as a static page with links to different projects? Do you happen to have any useful jekyll tips?

By the way, here's a drop-in "fork me on github" banner that works with jekyll:

<a href="http://github.com/YaleSTC/reservations"><img style="position: absolute; top: 0; right: 0; border: 0;"
        src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>

[shippy]

Agreed -- all three resources should be properly linked through to one another. Also, I think it making yalestc.github.io a disambiguation page for our different projects would be awesome.

As for jekyll tips, one semi-hack @squidgetx applied in our articles overview is automatically listing all pages with a given layout. Thus, giving the same layout to thematically related pages will allow you to auto-generate a table of contents. One potential downside, though, is that there seems to be no constant sort order of those pages, so they might appear in a different order upon site re-generation.

[orenyk]

I like the idea of targeting the different sources of documentation to different types of people. Let's make sure our github,io home / landing page is a well-designed portal that will direct people to the appropriate documentation.. I haven't had a chance to look through everything properly but it looks like things are off to a great start. Thanks!

[jasonkliu]

@shippy Have you ever run into the issue where the jekyll page looks like an extremely blown up version of the page without css? I had this on the shifts repo, then it mysteriously fixed itself, and then it came back again. Everything works when I run jekyll serve but outside of that everything breaks.

According to http://jekyllrb.com/docs/deployment-methods/ since Jekyll statically generates pages, I can copy the _site folder to a remote server and everything will work. I tried to do the same process with the shifts and reservations repos, and get the same kind of problem. I think I'm overlooking something but it's hard to Google this problem.

Here's an example from loading the page from the _site folder:

[shippy]

@jasonkliu Yes. We had this happen to us in two cases:

1. Ill-defined url: and baseurl: in config.yml. Url is the root server; baseurl is the folder on the server. Check whether the leads to any real location; if not, correct for it.
2. http v. https. If you're using SecureEverywhere, github will allow you to redirect to an https version of the github.io site -- but if the links to an http version (or vice versa), modern browsers will refuse to render it in order to maintain cross-site security. (Thanks to @dgoerger for catching this.) To solve for this, make sure that the website is consistently accessed on a single protocol.

Does YaleSTC/shifts/gh_pages contain the faulty code? Right now, https://yalestc.github.io/shifts/ displays just fine to me...

[dgoerger]

The Shifts doc still fails to be over a fully-HTTPS channel. See the warning triangle in the address bar:

This is a consequence of Mixed Content Blocking (MCB), and has been a problem with both Firefox and Google Chrome for over a year. Both browsers currently block Mixed Content, which on HTTPS pages is any element served insecurely over HTTP (not HTTPS). The issue with HTTPS-Everywhere is that it is a browser extension which forces HTTPS on domains which support the secure channel. @shippy worked some magic on the Reservations wiki code to always redirect all elements to the HTTPS version, which resolved the issue for the Reservations documentation.