SEAMS

Site for the Software Engineering for Applied Mathematical Sciences (SEAMS) workshop, an ICI3D clinic. Jekyll site (built with the github-pages gem), deployed to GitHub Pages at https://ici3d.github.io/SEAMS/.

Migrated from GitLab (gitlab.com/SEAMS-Workshop/seams-workshop.gitlab.io) into ICI3D; see #1. Theme and schedule-workflow integration are tracked against ICI3D/ICI3D.github.io#56 / #54.

Using Jekyll locally

From the repository root:

1. Install Jekyll.
2. Download dependencies: bundle install
3. Build and preview: bundle exec jekyll serve
4. Open http://localhost:4000/SEAMS/.

Deployment

.github/workflows/pages.yml builds the site on every push and pull request; pushes to main also deploy it to https://ici3d.github.io/SEAMS/. Pull requests build only, to validate.

The base path is set in _config.yml (baseurl: /SEAMS), and internal links use the relative_url filter, so a future custom domain serving the site at the root just needs baseurl: "".

Editing

Work in small chunks, one topic at a time: branch (or fork) the repo, make the edit, open a pull request, and a maintainer reviews and merges. You can edit directly in GitHub's web editor (press . in the repository, or use the edit pencil on any file) and open the PR from there.

Content Organization

The SEAMS site content is organized into several jekyll collections:

• warmups (_warmup): mental calisthenics. As the name suggests, the warmup exercises for each day. short puzzles. code katas. etc
• topics (_topic): brief outline of a concept + reference links. for use outside of discussion session
• sessions (_session): material for discussion sessions -- anything people need to download, stuff to display, questions, etc
• practicals (_practical): toy problems to focus on particular topics - paired with the discussions to help participants focus on the particular SE concept we discussed, and prep them to apply that thinking to their project
• project (_project): guided work for participants particular projects

To learn more about collections, see this. The gist of our use, however, is

More Details on the Blocks of Content for the Course.

• Reference Material (_topics):

• meant to be read-ahead and take-away
• develop a reference list / reading material / etc page

• Sessions / Discussion (_session):

• provide the rough pitch why the participants should care about this topic / perspective, and how they should think about it
• visit ~10 high level concepts within that topic, and how they work together (& with other topics)
• plan opportunities for interactive learning on these concepts: some mini task (~1-3 minutes) in pairs, or full cohort Q&A (~5 minutes), etc

• Practical (_practical):

• have an on-computer exercise, working with a toy problem
• should build in complexity; at least 3 levels that everyone will do, with a few more for people that really get it
• should NOT entail a lot of keystrokes to do right; the practical time should mostly be people struggling with new concepts / approach, not rapid-fire typing
• will need to prep code and input in addition to directions

• Project:

• provide a list of questions / tasks to give to participants to apply to their own work
• these questions should also suggest how the results can be incorporated into project
• also need a rubric / guidance / etc for other faculty to evaluate against to help them provide feedback to participants

Some Example / Reference for Blocks of Content

Project Planning & Design Session, ~10 concepts might include:

1. Requirements
2. Separation of Concerns / Design Patterns
3. DRY vs KISS vs Too-Much-Magic
4. Testing - validation vs verification vs performance (overlap w/ workspace org - having testing infrastructure),
5. process / work flow maps & pseudo code => real code
6. documentation (overlap w/ workspace org)
7. distribution (overlap with reuse & reuseability)
8. general coding best practices (conventions), etc...

mini exercises: code "telephone"

Project planning & design practical: toy problem to do with morse code. tasks: figure out work flows for parse, then de-parse, then identify overlap, then propose useful separate of pieces (e.g., reference non-code file for translation map, input / output separate from core dot-dash to alphanumeric and vice versa

Project planning & design applied to their project, example tasks:

• draw the flow diagram for each of the pieces your research work associated with this project, including inputs, outputs
• across those flows for each part, identify the "conserved" pieces
• list the requirements for your project: what kind of inputs must be used? what sort of outputs? what analysis rules must be met?
• what are possible intermediate products in your work? what are the dependency relationships between those pieces?
• what part of your project is specific? what part is generic to similar problems?
• what is the 1 sentence description of your project? ...the 1 paragraph? ...the 1 page?
• who is the audience / customer for this work? how will they use the work? what context do they work in?