Modern update for 2015 and beyond

[sukima]

I came across this really excellent CYOA style document on Git. Unfortunately, it seems outdated. The information was accurate but the format was difficult to navigate. The reason is that it used a linear display format for non-linear content. Using anchor tags allowed a user to jump from on section to another which allowed the non-linear navigation but it introduced two problems:

• A reader can quickly loose their place and not know where the are or were. This is the impetus of the breadcrumbs and history API (more on that later).
• Once a section was complete it is difficult for the reader to know if the next header was meant for another non-linear path or a continuation of the current context.

The medium of the content (mainly un-styled HTML) is lacking in some respects to a non-linear document. And as such needed several technological workarounds:

Because of my heavy use of anchors for navigation, and the utter lack of flexibility in the markup language this document is written in, it is important that the document be long enough at the bottom to complete fill your screen so that the item your link directed you to is at the top of the page.

I would like to propose a different approach to non-linear documentation. To do so I made some requirements on the project to pick the right tool for the job:

1. Requires the ability to follow a path of logic
2. Requires the ability to travel back up that path and explore other paths.
3. Requires ability to jump directly to a section if the reader know a little about it.
4. Requires the ability to serve via GitHub Pages.
5. Can not require any server resources other than file serving (i.e., static site).
6. Can be downloaded and used off-line.
7. Must be usable on any system (universal document).
8. Is able to be contributed to via GitHub's Pull Request cycle.

With these I found the TiddlyWiki project perfectly suited. In fact the Choose-Your-Own-Adventure building tool Twine uses TiddlyWiki (an old version of it) under the hood.

This pull request was a conversion from plain HTML to TiddlyWiki. You can see it in action via http://sukima.github.io/GitFixUm/ (my fork of the gh-pages branch). It addresses the above like so:

1. In the TiddlyWiki nomenclature each article is called a tiddler. As with most Wikis (e.g. wikipedia) they easily link together. As a user clicks on a link a new tiddler is revealed allowing them to unveil each step of the path through user interaction.
2. Every time a tiddler is opened it is added to the story river (a stack of visible tiddlers on the page). This allows a user to scroll back up and see the path they took. If they branch on that path the story river adjusts accordingly and logically. TiddlyWiki also allows the reader to customize their current view by manually closing any tiddler they are done reading.
3. TiddlyWiki has a vast array of navigation options. Beyond just links to each entry, it has table of content's, recent entries, tagging, and a very efficient off-line textual search. The latter helping readers explore more efficiently if they have an idea of what they are looking for.
4. TiddlyWiki is a single page app with all the logic, style, and assets built into one HTML document. Therefore ∴ ir it perfect to be hosted as a static page using GitHub's gh-pages.
5. To be specific TiddlyWiki has two modes of operation. The first (and what you see in this pull request) is served via a Node.js application. This is specific to development as the saved output is version control (i.e. Git) friendly. The second method is a single HTML document. The Node.js application can compile the individual files into one static HTML document ready to be placed in gh-pages. Essentially the later build step make development easier although it is not required as the two methods are interchangeable.
6. TiddlyWiki is an HTML implementation of a quine (A.K.A self-copying program). A reader can hit the save button at anytime and it will download a copy of itself (including any state the user was in at the time). It also means that they can make edits and save them for personal use or send them in as pull requests or via email. TiddlyWiki has a robust import system allowing anyone to import media including other TiddlyWikis and selectively choose which content to import or skip. This is great for readers to play with and send in improvements.
7. Since the output is standard HTML5 and JavaScript it is a universal program. Specifically all modern browsers.
8. As explained above a contributor has two ways to send updates. Either via a modified copy of the file in which case you simply load up the Node.js development server and copy and drag the changed HTML file to the browser to start the import/update process. And or the contributor runs there local version from source and makes changes. In either case the result is a series of text changes that are Git friendly and easily pushed to GitHub as pull requests.

I hope this is found useful. I found the non-linear method of documentation quite enjoyable.

P.S. One of the sections had a disclaimer regarding the need to replace the keyword $master with the branch name the user was interested in. I felt this was harder to read so I had a text box there and told the user to enter the branch they were interested in and the page auto updated. The same trick could be used in other places to make the documentation more interactive.

[gene1wood]

For anyone who didn't read the entirety of the text above in this PR, the content of this PR is live at http://sukima.github.io/GitFixUm