A story is an ordered collection of resources drawn from the site and elsewhere. Most resources are
webpages, but they also can be pdf files or some other file type that the browser knows how to open.
All of the story pages should be focused on a common theme. Each should present some part of the story
in a fairly complete way. They may provide links to other related materials that are not part of the
story itself.
Stories help us to find a good starting point for reading the theme's materials, and concluding
when all of the site's relavent material has been presented.
Stories published here already:
C++ Story - introduction or refresher for C++, the language used to develop most of the code in this site.
∞ Data Library - a guest story outlining a very ambitious and interesting library for capturing
research data.
MLiPS - a guest story proposing an interesting pipeline for Natural Language Processing implemented
using PowerShell cmdlets.
SiteStory - the story you are now reading.
I expect to create additional stories for the design of the StoryTeller, the design of this site,
and to invite more guest story tellers.
Stories appear to be an engaging and useful way to introduce topics relevant to the
repositories and the process of documenting them, as well as provide a forum for guests to describe
interesting things they are working on.
Complementing stories, we will soon start linking to YouTube videos, that walk through stories as well
as other topics.
How are Stories implemented?
Each story time-line is defined by a story file loaded by the StoryTeller webpage, as shown in the
upper right of Figure 1. The story file
contains a sequence of links and sibling text blocks. Each link refers to a story page or file.
The link's label is used in the story Table Of Contents, available as a dropdown list in the
StoryTeller interface, shown in Figure 2.
Each link's sibling text block provides page specific commentary. That is visible only when a
user presses the [?] button at the top right of the StoryTeller interface.
Adding or inserting another page is simple. Just provide another link and sibling text to the story
file. Of course a site user can't do that, but it's easy for the site administator to do so.
When the user loads the StoryList into StoryTeller - that happens automatically at startup - she is
presented with a link to each story. When she clicks a link the corresponding story file is loaded.
JavaScript included with the story file analyzes its TOC information and stores that as a JSON string
in localStorage. The StoryTeller reads that information and creates a pages array of JavaScript objects
with properties: url, name, and pageNote text.
urls are used to sequence through story pages, simply by sequencing through the pages array,
based on user clicks on the [Next] and [Prev] buttons. The page
names are used to build a table of contents, viewed by clicking on the [TOC] button at the upper
right of the StoryTeller interface.
You will find more details here: StoryTellerDesign.html.
Stories are an interesting way to find and explore site material on a specific topic. My experience
writing stories is that some additional transition pages are neccessary to build a coherent story,
pages that otherwise would not be on the site. However, that relatively small effort helps use the
site effectively.