about
Site Design
3/04/2022

Site Design

"Design is where science and art break even."
- Robin Mathew

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.

Purpose:

This site was designed to hold collections of code developed for graduate classes at Syracuse University and, after retiring, code developed as part of a collaboration with former students. That initial purpose has expanded to include a growing collection of resource materials for software development. That was originally focused on development with the C + + programming language, but for the last year has focused almost entirely on Rust. A secondary purpose is to explore ways to effectively communicate complex technical information. In the figures below, you see five different UI designs, each tailored to display a particular kind of information. One part of that exploration has resulted in several UI components for the site, based on the W3C specification for a Web Component. The most commonly used component in this site is an image sizer. If you click on the body of one of the figures below, it expands. If you click instead on the title bar, it contracts.
Figure 1. Site Structure

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.
Figure 2. SiteMap UI

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.
Figure 2. Home Level UI

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.
Figure 3. Repo Doc Page

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.
Figure 4. Rust Story UI

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.
Figure 5. Rust Bite UI

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.
Figure 6. BuildOn UI

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.
  Next Prev Pages Sections About Keys