Stanford CS184

[gellertnp]

Final prototype of data playbook for cs184

[david-sanabria]

Some initial comments on the proposed changes:

Observations

1. One large pull request for all of the proposed changes is very hard to merge and any breakage will be difficult to troubleshoot.
2. Deleting a page entirely means that there will be orphaned links to the playbook, which will result in user frustration and reduced use of the web site from external locations, including the CHHS home page.
3. The nav sidebar being always visible

• causes problems with printing and needs to be hidden in the print view (via CSS)
• is a problem when the screen size is small (e.g. mobile) and no longer "responsive"

1. use of the {{ site.baseurl }} Jeckyl variable results in a number of absolute links across the site. This is generally a bad idea because it means that someone is going to modify that variable when they work on the playbook.

Suggested Actions

1. The changes in this PR need to be moved to multiple, smaller PRs so the changes can be tested and evaluated in smaller sets. This will make troubleshooting any changes easier. I suggest creating a new branch with all of the proposed changes and merging changes in smaller groups from there.
2. Need to setup redirection for the renamed pages. there are a couple of methods that can be used, and they need to be explored
3. Modify the CSS file controlling the sidebar so that the sidebar is hidden during printing. Look for ways to make the sidebar shrink back into the "hamburger" menu when the screen is too narrow (e.g. mobile, responsive).
4. Eliminate the use of the {{ site.baseurl }} variable by editing pages to use the relative path to assets and pages. Look for ways to use a Jeckyl variable that points to the right local file (e.g. named reference) in a way that allows the site to mitigate the base URL variation resulting from forking or local development.

[david-sanabria]

Enhancement: Need a way to print the entire Playbook into a single document

We need to use the built in capabilities of Jeckyl to create a single page that pulls in all of the content from the individual site pages in a single web page, so that the page can be printed to a document.

Rational

• Governance requires some review by non-technical stakeholders
• Stanford students created a copy of the site content as a document, which they then saved as PDF. This is very duplicative work, and leaves a lot of room for transposition and copy/paste errors.
• Single page view would make the content more portable, based directly upon actual site content.

Technical notes

1. Jeckyl (tech behind GitHub Pages) allows for site pages to be iterated over in a loop. This method can be used to iterate over all site pages using a page especially prepared for this purpose, with it's own page category.
2. Using the "Redirect" template proposed in the previous comment, existing pages that get renamed can be marked as "redirect", which means they can be ignored for this single page view.

[david-sanabria]

Suggestion — Track Site Content Standards for Contributors

• The feedback in this PR suggests that there need to be some standards for content submissions
• The standard for such documentation is to add to a CONTRIB file, the repo README or wiki, or all three of these.
• It will be hard for us to enlist the aid of crowdsource contributions if we do not have some clear standards for contributions.