The diagrams and some of the commentary in this page are out-of-date. The descriptions are correct,
but incomplete and the menu diagrams show the old menu-system, not the newest for the site. That should
be fixed soon. Well, eventually.
Main Structure:
Figure 1. shows some of the site's structure. At the top menu the Repos dropdown discloses links
to index pages for Rust, C + +, C#, JavaScript, and Other repositories.
Each of the repository index pages links to documents for many code repositories. Each document, in turn,
links to a github code repository.
The Stories dropdown provides access to stories defined in the site. Each story is a set of linked pages
that focus on a single theme.
Essentially the two groups of items in the center and on the right of Figure 1. represent code containers
and story presentations, respectively.
On the left, linked to the SiteMap dropdown is a SiteMap page that supports navigating directly to
almost all content in the site. That page also provides a table of keyboard commands for quick navigation.
SiteMap:
The SiteMap is a top-level page and so has a Home page navigation menu at the top.
Its contents are, however, quite different from other Home-level pages.
The entire page consists of blocks of links with descriptions, with one exception. That is a
keyboard map that identifies key presses which results in page actions, anywhere in the site.
The first three blocks, "viewing order", "Help with Site", and
"Rust References Trail" provide links focused on the process of learning Rust
and this site.
The next block "Stories" provides links into the Rust Story, C + + Story, and several
stories related to Rust. Note that a story is a connected thread of pages that focus on a single
topic and can be navigated with "Next" and "Prev" buttons or the N and P keys
(key actions are not case sensitive. h and H do the same thing).
The next block provides links into all of the site's code repositories. Each repository has
a documentation web page, and each of those link to a specific github repository.
The remaining block contains links to engineering content, presentations, and to videos.
Repository Summaries:
Each index page, shown in Figure 2., has a set of dropdown menus disclosing all the repositories for each
language category. Those are factored into: utilities, tools, re-usable components, libraries,
projects, and demonstration code.
In Figure 2, the dropdown menu for demos is visible. Each entry in the dropdown links to a documentation
page for a demo repository.
The body of the page also has details sections for each category. The Components category is expanded to
show more information than available from the Cmps dropdown.
Each of the links in this page go to a documentation page for the repository which, in turn, links to
the repository code. An example is given in Figure 3.
The page UI is the same as all of the other top-level pages.
Repository Documentation:
Each repository doc page, like that shown in Figure 3., provides information about the concept, design,
operation, and status of code in that repository.
Some pages provide a lot of design detail, some do not. The most interesting or challenging repositories
do provide details. These are intended, in part, to hold onto the code's design concept for
re-use and maintenance.
The intent is that a potential user of the code can quickly see what it does and how it works. If that
meets the user's needs, then forking the repository let's the developer get the repository code
installed and running very quickly.
Stories:
There is a lot of technical information about programming languages and related topics in the site,
and it can be difficult to sort out what to look at. Stories are intended to help with that.
Stories are sets of linked pages, all focused on a single theme.
Some stories, e.g., C + + Story and Rust Story, are narrative descriptions of a language with mulitiple
chapters, examples, and exercises. The intent is that you will read them, over time, from end to
end.
Note, from Figure 4, that the stories UI consists, not only of the top main menu, but also a menu
specific to this story, with chapters shown on the lower right side, and sections in the current
page shown at the bottom.
This structure makes it quick and easy to search for a particular piece of knowledge.
So this makes it easy to navigate both to places within the story and to places outside.
Bites:
Bites are a set of linked pages each of which explores a single feature of its parent story. A Rust Bite
describes a single feature from the Rust Story, providing examples and exercises.
They may have more details than their source story, but stand in isolation, outside the context
of the parent story. They are used
to help a designer with a particular set of coding tasks, like error handling.
The distinction between the parent story, Rust Story, and a child story like Rust Bites is that
the parent provides a narrative description spanning the whole language and some of its libraries.
The Bites, instead, focus on a single language feature.
Note that the Bites UI has omitted the main top-level menu. Instead it provides links to navigate up
and down the sequence of Bite pages and, as well, links at the top right to popup to the repository or
go home.
BuildOn:
BuildOn pages are focused on implementing a specific project. They specify the whole project.
Then factor the project into packages, each with a specification. Some have sample starter code
to help those new to Rust to get started.
The first page, Intro, introduces the BuildOn process and provides preliminary references. The second page,
Step #0,
specifies the complete project and adds more targeded references. The remaining pages each focus on
one package of the project's implementation.
BuildOn pages all provide a navigation panel on the left which can be hidden with the "toggle menu"
button. Unlike the Bites UI, the left panel is open by default, keeping focus on the the project steps.
Figure 7. Idioms & Patterns UI
Idioms and Patterns:
Idioms and Patterns are a different kind of Bite. Each takes a common programming task, idiom, or pattern,
and provides a sample implementation in Rust, C + +, and C#. The intent is to help readers understand Rust
code by comparing code in another language that is doing the same thing.
IaP pages are designed to make comparing code relatively easy. Note from Figure 7. That each page has
three panels displaying C + +, Rust, and C# code. Either the C + + or C# panels can be hidden to focus on
comparing Rust with one specific language.
Other than the panel structure, IaP pages have the same UI as the Bites.
I expect this Idioms and Patterns story to become one of the sites more valuable features. Right now
it is just beginning, so there are only a few entries.
Design:
All pages in the site are static, with styles and JavaScript files that are tailored to the type
of material presented.
Most menus are generated with Javascript. That makes adding or changing menu links easy, because
there is only one place to change - the JavaScript source file.
Status:
Work on the site began when I retired, at the end of May 2019. A significant part of the intended code base
has been installed and documented.