Lab 1: Github Portfolios and User Story Mapping

To stand out in the competitive software industry, as well as to engage potential contributors, a complete GitHub repository is an effective tool to showcase your work. In this lab we will introduce you to an overview of GitHub, how it works, and show you some examples of strong repositories. Finally, we will discuss using GitHub as a design and coding portfolio, which you can use to showcase your work and attract prospective employers. As a running assignment in this lab, you will add to your GitHub portfolio, which will be assessed in a live interview in the final lab of the semester.

Version Control

Git is version control software responsible for backing up different version of your source code over time, and letting you restore or jump between different versions. Git aids in backup, branching, and collaboration. A Git Repository (repo) is the name for the database in which source files are stored. GitHub is a cloud service, owned by Microsoft, which can host our repositories remotely. VS Code is an open-source text editor which can easily synchronize local files to GitHub repositories.

Our Setup

What we’re going to be setting up:

Install VS Code…

Download and install VS Code. The default settings are typically fine.

Overview

1. Left panel - explorer, search, extensions, git
2. This area changes depending on what is selected in (1).
3. Tabbed interface lets you have multiple files open at once.
4. Centre stage is where you will edit your code
5. The minimap is a zoomed out view of your code, and helps you navigate quickly.
6. Terminal, debugging and output appear down here. Sometimes this area is hidden.
7. See which modes the editor is in, like language, line endings, tab size, etc.

Install Git

Download and run the installer for your system. (e.g. 64-bit windows setup).

Most of the installation defaults are fine, but watch out for these ones:

Configure Git

We need to do some initial setup for git.

From the command line, configure git:

git config --global user.name "FIRST_NAME LAST_NAME"

git config --global user.email "MY_NAME@example.com"

Use your own name, and the email you plan to use for registering a GitHub account.

Spelling must be perfect, or it will silently fail, leading to later frustrations!

Create a GitHub Account…

Pretty easy to do, just follow along with the provided instructions. Recommended to use your real name and a professional email.

Creating and Linking a Repo through VS Code

Creating a Repo through VS code is easy. First we need to create a folder:

And trust it:

Then add a file:

And publish to github:

Oh, but we need to authorize VS code to use our GitHub account with O-Auth:

So, now we need to create a remote repo on GitHub:

And show which files we are going to send up to the remote:

And push it!

Check it out, we have some files on GitHub:

Staging

So VS Code has abstracted a lot of the Git process. Let’s examine it in depth.

Your files can exist in 4 states:

“Working”, “Staging”, “Local Repo” and “Remote Repo”

By default, files are in the working (U in VS Code) state.

• When you run the add command (+), a file is moved from working to staged. This means git knows to include it next time work is checked in with a commit.

• When you run a commit command (✓), all of the staged files are backed up into the local repository, and the local files are returned to the working state.
  • This means, if you want to do another check-in, you will need to add them again.
  • Commits need a brief message to explain the reason for the commit, usually phrased as “verb-nouns”, e.g. “add readme md”
• Finally, when you wish to synchronize the local repo with the remote repo, you will use a push command.

Let’s see how this is done in VS Code.

Let’s add another file:

Add it and commit it:

Push it:

Check it on the website:

There’s waaaay more to Git and version control than this, but that is for another course. This should be enough to get you uploading files for your portfolio.

Let’s look at some good GitHub Repos, Profiles and GitHub Pages to see what can be done with GitHub.

Good Repos

GODOT Game Engine

VS Code

TensorFlow

BootStrap

You Don’t Know JS

Good Profiles

You may use a profile readme markdown file for yourself to let people know who you are. Examples:

List of Profile Readmes

GitHub Pages

GitHub pages allow hosting static websites for free. Examples:

Best GitHub Project Pages

GitHub Best Practice

We won’t discuss the how’s of all of these in this lab, but it’s good to keep in mind for the future!

Good Commit Messages - Brief, accurate. Verb-Nouns. A focus on “why” over “what” when it’s not obvious.

• e.g. “add lab 1”
• e.g. “add dodge mechanic in player class to help with boss battles”
• e.g. “fix death-cam bug in undead parish to prevent sen’s gate skip”
• e.g. “refactor controller class for future proofing”

Don’t Add Junk Files

• Some IDEs add extra stuff that doesn’t matter for your source code, e.g. compiled binaries, cached thumbnails, editor settings
• You can find common “.gitignore” files which will automatically prevent these from being pushed
• If you want binaries, use releases

Appropriate Branches

• Branches allow developers to work on features independently, and then merge into main when all bugs are fixed

Dependencies / Compilation Instructions

• Having a few sentences on how to compile your application ensures potential users and collaborators can start using your software right away!

Issue Tracking

• Let your users know how they can report bugs, and if you plan to maintain the repository

Pull Requests

• To foster community collaboration, state if/how you will handle pull requests

Open Source Licensing

• If you wish to release your project to the world, source included, use an open source license, such as Creative Commons, MIT or GNU GPL. Creative commons should only be used for creative works rather than source code, the MIT license gives derivative projects the most rights, whereas the GPL forces derivative projects to also remain open source.
• This is not required to use GitHub, and you can even keep your repositories private.
• If anything is not covered by the license, let the users know explicitly (e.g. Trademarks)

• A UX exercise credited to Jeff Patton originally documented in his article “It’s All in How You Slice It (2005)” and later a book published by O’Reilly.
• Has grown iteratively over time by various developers.
• An exercise which produces a card-based planning model.

Guiding Principle

• Challenge the old Software Engineering adage: “If you build the highest value feature first, users will love your release”.
  • This adage is false when lacking required low-value (secondary) features.
  • e.g. If you are designing a photoshop clone, a high demand feature might be cool new AI tech for context aware fills.
    • But if you are missing the basics (crop, resize, etc.) then your tool will not get much long term use.
• We hope to use this tool to discover a set of core features, primary and secondary, which should be prioritized in a Minimum Viable Product (MVP) to make a product people will actually want to use!

Who should participate in User Story Mapping:

• Never one person!
• A team of four to eight stakeholders from different roles
• Domain experts, testers, UI designers, business people

Originally, eight steps were given to describe user-story mapping. These need not be followed rigidly, but provide a nice narrative to the process.

1. Collect Features
2. Add Details
3. Place Cards in Sequential Order
4. Group by Frequency
5. Note Logical Breaks in Workflow
6. Mark the First System Span
7. Fill in Build Estimates
8. Slice and Serve

In detail:

1. Collect Features

   • Answer “What does our software do?”, from a user perspective.
   • Write these on business cards or index cards

2. Add Details

   • What kind of user uses the feature, (role, persona, etc.)
   • How often, (daily, weekly, monthly, hourly?)
   • How valuable is the feature? (high, medium, low)

   Original Proposed Example Card:

   ---

   create po for vendor

   (merchandise buyer)

   frequency: weekly

   value: medium

   ---

   • With all these cards this might feel like Monopoly.

   • Note that this style has later been standardized by Mike Cohn to the User Story approach:

     • As a type of user I want some goal so that some reason.

   • This method is preferred in this course where appropriate.

3. Place Cards in Sequential Order

   • On a poster board:
     • label the X-axis “Usage Sequence”
       • We use the western convention that left happens earlier, right happens later, though this can be modified for working in other cultures with different conventions.
     • label the Y-axis “Criticality”
       • Features at the top are always used, features at the bottom are rarely used

                               Usage Sequence
           Used Earlier                                       Used Later
           <------------------------------------------------------------>
           (Always Used)
           ^
           | 
           | Criticality
           v
           (Never Used)
         

   • Usage sequence refers to tasks that have to happen in order,
     • e.g. collect ingredients before starting cooking
   • If events happen simultaneously, arrange them logically.
     • e.g. If I asked you: “List everything your system does”, what order would you list the features?
     • That should be the order you place them.
   • As a group, place the cards in just one row across the top.

4. Group by Frequency

   • As a group, adjust the vertical position of each card based on how critical they are to the system success…

   • We’ve gone from playing Monopoly to Twister!

   

5. Note Logical breaks in Workflow

   • As you go left to right through the model, you’ll find breaks, typically where tasks shift from one person performing the task to another.

   • Draw in vertical dashed lines at these points to divide into business processes.

   • If you are having difficulty finding these divides, discuss why, which may lead to important new insights about the project.

6. Mark the First System Span

   • Identify the smallest set of features to be minimally useful in a business context.

   • Draw a horizontal line under the row which makes up the first span

   • The line does not need to be straight across - weave up or down to grab the features you want or exclude features you don’t want.

   • These are the highest priority features in each business process

   • Some vertical lanes might be empty.

   • This top row represents the bare minimum of features which must be in your first release, even if this is only an internal release, so that you can start testing.

     • This initial system span is called a Minimum Viable Product, MVP

7. Fill in Build Estimates

   • Have devs write implementation time estimates directly on the cards. Add up the values across the top line – this is time to the MVP

8. Slice and Serve

   • Have the business people decide which features need to be in each successive release, by drawing additional horizontal jagged lines across the remainder of the poster.

   

• In Software Systems Engineering, an “Artifact” refers to any physical (or virtual) objects created in the process of aiding software development. This includes things like User Story Maps, Kanban boards, UML models, requirements documents.

Looking at the physical artifact we have developed, we can see:

• We’ve found dependencies. We’ve found criticality.
• We know the features set to get your system up and running.
• We can also see functionality needed for a single person or role

Limitations

• Useful processes rarely remain static. This one naturally evolved with contributions from the original author and other contributors.

• The biggest limitation of the original model was “Granularity”.

  • All of the current tasks are framed as small tasks.
  • We need to extract the big picture to contextualize the tasks.

Further Advances

In the aim of addressing the granularity problem, the following adjustments were adopted:

• In the top tier is the “Big Stories”, a.k.a. User Activities (Norman)
  • Commonly called Epics, they are more like “chapters” in a story
  • This row is called the Backbone
  • Provide context to the tasks, so we don’t lose the big picture
    • If a unit of work is too big to be used to make meaningful estimations, it should be further decomposed
• The second row down are the Steps. together making the Walking Skeleton (Cockburn).
  • You should be able to walk through the tasks in this row and feel everything fits together logically
    • There should be no missing steps, no gaps in logic
    • It can be useful to do this process with the client. This will help you identify what to build first.
  • Some groups use a different card color for this row.
• Everything underneath are Tasks, or Details in decreasing frequency of use.
  • These are our skeletal ribs.
  • Typically a third color is used, though tasks may use a variety of colors as needed

• Some sources use minor differences in terminology for different levels of granuarity

In the real world, Software developers rarely stick to rigidly defined rules, and modify these techniques as needed.

• You’re a problem solver, you should be using whatever tool best solves the problem, not trying to fit the problem to a rigid tool!
• Some people want more levels of granularity, some want fewer.
• You may see two colours of cards used, one for the backbone and one for tasks, or three colours, for the backbone, walking skeleton and tasks, or more.

Finally, software has made this process completely virtual, which we will demonstrate using Stories on Board.

Let’s head over to storiesonboard. Tim should have set you up with accounts.

In order to quickly see the capabilities of the software, you should create a new board, and instead of starting from scratch, start from the Guide Map:

You should see a new board:

It is somewhat intimidating. Let’s take a look around, moving clockwise from top-right…

1. Here we can navigate between this and other maps
2. In this section we can add collaborators, zoom our map, filter which cards are displayed, and change what appears in the sidebar.
3. This is the sidebar, in this area you can perform various task depending on what you have selected from section 2, such as view board conventions, edit personas, and discuss the board.
4. Center stage - this is where you will spend most of your time working, adding cards, organizing them, adding time estimates, and moving them through the various stages.

Let’s zoom in on the upper left of center stage:

1. As the vertical lanes tend to correspond to different people or roles, it may make sense to assign personas to these tasks.
2. Time estimates for our larger stories are derived from the sum of the time estimates of the smaller tasks below them.
3. We can create releases and assign cards into each. Some feedback is given for the release, including how many cards and hours remain, and how many cards are not yet estimated.
4. We can set the status of a given card, from the options of TODO, READY, DOING and DONE.
5. We can set a time estimate for each task, which is used for computing the total time for a given lane, as well as the time remaining for a given release.
6. Cards can be annotated with a number of symbols explained in the “About This Board” legend.

We can also see an overview of our progress by clicking on the progress part of the release, e.g. 14 CARDS, 76 LEFT OF 91 HOURS

Simple card modifications such as renaming and adding can be accessed from the menu in the bottom right of a card

Let’s Interact with a card in detail…

• Right Click to change color
• Double Click to edit in detail…

1. Here we can see the title of the card
2. The user story, as well as some details about the card go here. You can use MarkDown to make this look better, add images, links, etc.
3. Comments for other members of the team
4. Modify the card
5. Details about the card such as status and estimate. You can add your time estimate here.

This is a good overview of the software. Before you leave the Guide Map and head into your own map, check out the cards in this region:

And if you want more help, check out the documentation here: Read Some Docs!

Imagine you are tasked with building an application for a food delivery service. Use User Story Mapping to plan building such an app.

In accomplishing this, think in terms of: Who are the users? What are the user’s goals(Activities), and what smaller operations must they do (Steps, Tasks) in order to accomplish this goal?

Video App:

Using StoriesOnBoard, create a new, private, solo board which represents the User Story Map for an application for sharing videos on the internet, e.g. YouTube, TikTok, etc. Focus primarily on the user side of the application. Perform User Story Mapping to develop a map which captures the most necessary user stories for this application. In accomplishing this, you should have:

• At least three epics in the backbone
• At least six steps in the walking skeleton
• At least 18 total tasks
  • All tasks need to have a name, status and time estimate, but the estimates need not be realistic
  • Edit the details for at least three tasks and try out different markdown features
• At least 2 releases, including some unscheduled tasks
• Experiment at least one extra feature, such as additional card colors, annotations or personas

The map does not need to exhaustively capture every feature of the application.

Hint: Try to think of different users of the application system, such as viewers, content developers, and administrators.

Running Assignment - Development Portfolio

• Start a new (private for now) GitHub Repo which will be your portfolio for the course
• Upon completing assignments, take screenshots and push them to the repo
• You can investigate GitHub Pages if you want them to be totally on the web
• Use GitHub best practices to create a high quality repo
• You will add to this repo all semester!
• For this lab, you only need to have a readme.md uploaded

Please submit the following

• 1. A screen capture of the overview of the User Story Map
     • Open the side bar to the left so that I can see your username
     • If this hides some of your tasks, you can do an additional screenshots so that I can see your name
• 1. Three screen captures of your three detailed tasks, one capture each
• 1. Include a readme.txt explaining which extra feature you tried
• 1. Include a screen capture of your GitHub repo so far, which should still be private

(This should be a total of 6-7 files)

Please submit to URCourses by the deadline.

J. Patton, It’s All in How You Slice It, Better Software, 2005.

J. Patton, User Story Mapping: Discover the Whole Story, Build the Right Product, O’Reilly Media, 2014.

J. Patton, The New User Story Backlog is a Map, Jeff Patton & Associates, Accessed 2021

M. Cohn, User Stories, Mountain Goat Software, Accessed 2021

A. Holub, Picturing Architecture: UML (The Good Bits), Pluralsight, 2016