South Bay Streets (SBS) – User’s Guide
© 2025 McQuillin & Associates Inc. -- Company Confidential
Guide Ver 0.7 – 2025-03-14 – For South Bay Streets Ver 0.8 – R. McQuillin
1. NOTE: ROUGH DRAFT – PARTIALLY COMPLETED – WORK IN PROGRESS
2. NOTE: This document is COMPANY CONFIDENTIAL with limited distribution. It has been provided to you for early review. Please do not forward, copy, or otherwise distribute it without prior authorization.
3. WARNING: This guide may be updated often. Avoid using outdated copies. Please note the version number above. A version history is shown at the end of this guide.
Contents
1.1 Who is this for (the Audience)?
1.2 What is South Bay Streets (Streets) and Why Use It?
1.4 Purpose of this User Guide
1.5 MAYBE: Use the
Training Site to Learn Streets
1.6 Use This Guide alongside the Application
2 Terms and Abbreviations (Application-Specific)
3 Major Processes Supported by Streets
4.2 Common Entity Concepts: Record Quality/Completeness
4.3 Common Entity Concepts: Record Lifecycle
4.4 Common Entity Concepts: Cloning / Versioning
6.9 Common Screen Features and Behaviors
6.9.1 Deep Linking / Link Sharing!
6.9.2 Find, Clone, Modify, Activate
7 Use Cases: Getting Things Done
8 Use Cases: General Use Cases for Everyone.
10.2 Add a Shared Goal (Client)
10.2.1 Find and Clone a Shared Goal
10.2.2 Modify and Activate the Goal
10.3 Create a Custom Goal (Client)
10.5 Add Projects to a Goal (Client)
10.6 Monitor, Review and Work on Your Goals (Client)
10.7 What’s the Difference Between ‘Preparing’ and ‘Active’ Goals?
11.1 Add a Shared Project (Client)
11.1.1 Find and Clone a Shared Project
11.1.2 Modify and Activate the Project
11.2 Create a Custom Project (Client)
11.4 Add Needs to a Project (Client)
11.5 Monitor, Review and Work on Your Projects (Client)
11.6 What’s the Difference Between ‘Preparing’ and ‘Active’ Projects?
11.7 Complete a Project (Client)
12.1 Add a Shared Profile (Client)
12.1.1 Find and Clone a Shared Profile
12.1.2 Modify and Activate the Profile
12.2 Create a Custom Profile (Client)
12.4 Add Projects to a Profile (Client)
12.5 Monitor, Review and Work on Your Profiles (Client)
12.6 What’s the Difference Between ‘Preparing’ and ‘Active’ Profiles?
12.7 Complete a Profile (Client)
14 Use Cases for Offers and Assets
15 Common Use Cases for Multiple Entity Types
15.2 Convert a Model Back to a Real Entity
15.4 Unshare an Entity (Client)
16 Use
Cases for Application Administrators
16.1 Managing Users
(System Access)
16.2 How to Impersonate
for Testing and Learning
16.3 How to Standardize
Custom Areas and Types
16.4 How to Change
Value Lists in the Database
16.5 How to Set
Facility-wide Options
20 Appendix: Use Case Template (Author)
Version History
|
Version |
Date |
Primary Author |
Change Summary |
|
0.8 |
2025-03-14 |
R.McQuillin |
Original: ~ 50% complete |
|
|
|
|
|
|
|
|
|
|
1 Introduction
1.1 Who is this for (the Audience)?
This document is for users who will create accounts in Streets and use the community commerce capabilities (planning, fulfillment, etc.)
1.2 What is South Bay Streets (Streets) and Why Use It?
(This section provides a quick recap. See the SouthBayStreets Introduction for a better introduction.)
South Bay Streets (“Streets”) is a web application that you use to create and manage a database of your goals and needs. If you do this, you’ll save time and money and stress and improve your shopping experience, and hopefully your life experience.
(South Bay Streets (“Streets”) also allows you to use commerce maps, and to create your own, and share them. How to do all this is covered in the document “South Bay Streets – User Guide for Maps”.)
Streets is your database. You create it and manage it to improve your life.
That’s just a very quick recap. You can find out more in the Streets Introduction document.
NOTE: Some sections of this document are not yet provided. These are often marked with “$FINISH$” or “TO BE PROVIDED”. If you need information that has not yet been provided, please contact the document author.
1.3 Other Info Sources
1. The SouthBayStreets Introduction
2. (Possible, $FINISH$) Specific user guides for roles: Sellers, Advisors, Support, Admin, “Map Owner”
1.4 Purpose of this User Guide
This is a guide for using the Streets app to complete your tasks. It describes:
· Major Processes. What you’ll be doing overall.
· Major Entities. The data you’ll be working with.
· Users. (User Roles) The types of people who use Streets and what they do.
· Screens. (Common Patterns) The web pages and email messages you will see when using the application.
· Use Cases. Step-by-step instructions for how to accomplish tasks.
· Putting it All Together. Using the basic skills to achieve the higher app functionn
· FAQs and Appendices.
1.5
MAYBE: Use the Training Site to Learn Streets
You can use the training site to practice. The training
site is $FINISH$. This is a completely different web site and database from the
production (live) application. You can modify data on this site without making
actual changes to live data. But make sure you see the warning below in
the header (“You are on the TRN site”) before changing any data.
$FINISH$: MAKE SURE YOU LOOK FOR THE TRAINING SITE
INDICATOR
Where does the data in the training site come from? We
take a copy of the production (live) data every now and then and move it into
the training database. So if you have an account on the production (live) site,
you’ll have an account in the training site.
Also, the training site normally doesn’t send out emails,
which makes it safe for you to experiment and learn.
1.6 Use This Guide alongside the Application
This guide has some screen shots, but not for all topics. If you can, we recommend that you open this guide on-screen next to the Streets screen(s) you want to work with and follow the instructions step-by-step using the live screen. Or you could print out the guide.
2 Terms and Abbreviations (Application-Specific)
NOTE: See also Terms and Abbreviations (General) in the Streets Introduction document. Those terms are also needed to understand this document. This is a list of additional terms for actually interacting with the application.
|
Term |
Meaning |
|
Actor |
|
|
Use Case |
A Use Case is a “How To”: It is a task performed by an actor (a user in a role) using the application to complete an operation. |
|
Page |
|
|
|
|
|
CDL |
A comma-delimited list, for example: “1,123,88” or “Lorem,ipsum,dolor,sit,amet”. |
|
|
|
|
|
|
|
|
|
3 Major Processes Supported by Streets
Here are the major types/groups of things you can do with Streets:
1. Use Maps when visiting a location (or preparing to visit)
2. Create and Manage Goals
3. Create and Manage Projects
a. Define Needs
4 Major Entities
See the Major Entities / Concepts section of the SouthBayStreets Introduction document.
That document describes Goals, Projects, Needs, and Profiles.
4.1 Common Fields
When you’re working with the entities, you’ll see that the entities share many common fields. This makes it easier to understand and work with the database. The Appendix: Common Fields (in this document) describes several of these.
4.2 Common Entity Concepts: Record Quality/Completeness
4.3 Common Entity Concepts: Record Lifecycle
4.4 Common Entity Concepts: Instance Type / Cloning / Versioning
Many entities have a Data Instance Type: Real or Model (or sometimes Test):
1. A Real entity is one that you are “really” using.
2. A Model entity is one that can be used (cloned) top create Real entities.
3. (A Test entity is just for testing the app and isn’t a Model or Doesn’t represent a real situation.)
4.5 Common Entity Concepts: Visibility / Sharing
Many entities have a “Display Scope”: Who can see it:
1. Personal-scoped entities can only be seen by you. They are ‘private’. These are things that you only want to manage yourself.
2. Network-scoped entities can be seen by you and the people in your network (of links and helpers). They are ‘semi-private’. These are often Real entities that you want help with, or Model entities that you have prepared for friends in your network.
3. Everyone-scoped entities can be seen by all, they are ‘public’. These are often Model entities that you have prepared for the world to use.
5 Users (User Roles)
Here are all the types of users (also called “Roles”) that may directly use Streets:
1. Guests. Everyone can view and use maps without creating an account. You’ll need to be a Member to customize settings or save any data or use any of the planning features.
Everybody who creates an account is a Member. Here are types of Members:
2. Clients. Clients are the owners of Goals and Projects. Clients are the $FINISH$.
3. Sellers. Sellers can fulfill Needs with products and services. They can also share model Goals, Projects, Profiles, and Needs that you can clone and use in your database. If a Seller shares one of these, there’s a good chance they can help you fulfill it – that’s normally why they share it.
4. Advisors. The outage leads can perform all tag management within their outage: copying tags from the library and/or another outage, adding tags, changing tags, printing tags, scanning tags, getting reports, etc.
Then, behind the scenes we have Support and Administrators.
5. Support.
6. Administrator. The administrator(s) can do anything/everything for their site, including adding and removing users, creating projects, managing needs. etc.
5.1 [NO]
Security Trimming
6 Screens
A screen is a visual element that you use to view information or perform a task.
A screen may also be called a page, for example, the View Goal page, List Goals page, etc.
This section is a quick introduction to the screens in Streets. The screens are listed here in the order they appear in the top menu (below). Some pages are reached from other pages.
6.1 Common Screens
You use Streets to work with entities (Goals, Projects. Etc.), so you’ll see the same type of screens over and over again for each entity – not always, but often. Here are some common screen patterns:
The next several sections are a list of common screens.
6.2 Common Fields
See Common Fields above under “Major Entities”.
6.3 List Entities Screen
This lets you see multiple entities at once. You can filter and sort to refine your list. When you find the entities you want, you can select them. This is also where you find the Add Entity button, to add (a) new entity(s).
NOTE:
· Once you get a list filtered and sorted the way you want, you can save that bookmark, email that bookmark to one of your links or helpers (COMING SOON), or Pin that page setup to quickly return to it.
6.3.1 Working with Lists
1. Filter.
2. Sort.
3. Show. Most lists can be shown as either a table, a set of cards, or a simple list of names only.
6.4 Add Entity Screen
This lets you add a new entity. Normally there are two or three options:
1. Shared. You can find and clone an entity that someone has shared. You’ll often see this ‘filter’ at the top of a list of shared entities. You can choose between entities shared by everyone or shared just by members in your network (friends, advisors, sellers).
Cloning shared entities is a great way to use the knowledge and work of others. See the Find, Clone, Modify, and Activate section below.
2. Create. Enter a new entity “from scratch”. (This screen and the Edit page are usually where you see the Common fields.)
3. Generate. You can use AI to create an entity based on prompting information.
6.5 View Entity Screen
This lets you view all the entity’s data in compact form. You can…
1. Click Edit to switch to the Edit screen, or …
2. Click Actions to pop up the set of actions you can perform on that entity.
3. Use the tabs to view other aspects of the Entity.
6.6 Edit Entity Screen
This lets you edit the main properties of the Entity, You can …
(This screen and the Create tab on an Add page are usually where you see the Common fields.)
6.7 Entity Actions Screen
The Entity Actions screen pops up when you press “Actions” on a View page or List page. These are actions that you can perform for that specific entity (or entities) of that type in that state.
6.8 Other Screen Types
TBP
Start Centers. (Dashboards)
Modals. (Popups)
6.9 Common Screen Features and Behaviors
6.9.1 Deep Linking / Link Sharing!
Once you get to a page you want to revisit or share, or you get a page set up the way you want it (like a list filtered and sorted just as you like) you can bookmark that page using the “Pin” feature in Streets (or your browser’s bookmark / favorites feature). Then you can quickly return to exactly where you were, even if it’s “deep” inside of Streets.
· You’ll want to “stay signed in” to avoid having to sign in each time you visit the page.
· NOTE that these links will show live data, not a “snapshot” of the “static” data that you saw (unless that data didn’t change).
Going further:
· You can also send these links to other members. If the member has permission to view that page / that data, they will be able to see it. (If not, they will get a “permission denied” message. (If that member “stays signed in”, they’ll go directly to the page. If not, they’ll just need to log in first.)
6.9.2 Find, Clone, Modify, Activate
6.9.3 Pinning
Once you get to any screen, and get it set up the way you want, you can usually Pin that screen and quickly return to it (from your Pin list).
6.9.4 Pictures
Most entities can have pictures. It’s very helpful to add pictures to your entities (1) to help you understand and recall what you’re doing, and (2) to help others help you, especially to help sellers fulfill your needs. On most View pages you’ll see a list of pictures. You can view the pictures in different sizes, add pictures, edit the picture information, and remove pictures.
6.9.5 Record Navigation Bar
View and Edit screens usually have a record navigation bar near the top of the page. These are the entities in the list from which you opened the View or Edit screen. You can use the navigation buttons to move back and forth in the list of records.
WARNING: If you make changes to a record, press Save. If you make changes and press a navigation button, your changes won’t be saved.
6.9.6 Validation Messages
(Need no explanation)
7 Use Cases: Getting Things Done
These “Use Cases” are “How To” tasks: How an actor (a user in a role) uses the application to complete a task or reach an end goal state.
The Name of the Use Case is the task name followed by the role(s) that perform it in parentheses, for example “Add a Goal (Client)”. Then, each Use Case usually provides most or all these elements:
· Trigger. What causes you to want/need to take this action now.
· Preconditions. (Starting Point) What preparations must you make, what must you have on hand, or what state must your database be in before you can perform this task.
· Procedure. (Steps) The steps you take to complete this task.
· Results. (Postconditions) The state are things in when this task is completed (new entity saved, entity updated, message sent, order processed, etc.).
· WARNING(S): Things to be cautious of when performing this task.
· NOTE(S): Other important aspects or implications of this task.
[See the Appendix: Use Case Template when authoring new use cases.]
8 Use Cases: General Use Cases for Everyone
Use Case topics are grouped by the type of activity. First, here are some Use Cases that anyone can use.
8.1 How to get help $FINISH$)
1. From the Help menu:
a. Click User guide for a comprehensive Word document (this document) containing guidance and Use Cases.
b. Click Application updates to see the application version and a description of application updates.
c. Click Switch to training site to move to the site that allows changing data without disrupting the actual production data.
9 Use Cases for Maps
Use Cases for Maps are covered in the document: “South Bay Streets – User Guide for Maps”.
These next sections are all about the planning and fulfillment capabilities.
10 Use Cases for Goals
General goal-setting is a powerful exercise and is outside of the scope of this guide. See the Streets Introduction for how to do that. We pick up the process here assuming you already have some goals defined or at least identified (that is, maybe you just have a name, and that’s it). If your goal is only identified but not really defined, you can use this form to enter the S.M.A.R.T. parts of the Goal.
10.1 Create and Manage Goals
$CONTINUE$
Streets is a database of your data to manage your goal-driven purchasing.
The Major Entities / Concepts are defined in the Streets introduction document.
10.2 Add a Shared Goal (Client)
This is a multi-step use case, consisting of these major parts:
1. Find and Clone a Goal
2. Modify the Goal
3. Activate the Goal
10.2.1 Find and Clone a Shared Goal
Here you’ll find and clone a Goal shared by someone else. The Goal doesn’t have to be a perfect fit for you, just a good starting point / template, because in the next step you will modify it to fit your specific situation.
Preconditions. You want to see shared Goals, and maybe load (a) Goal(s) offered/shared by someone else.
Procedure.
1. Open the Add a Goal screen from either your Start Center or from the List Goals page.
2. Click on the Shared tab. You’ll see the list of shared Goals, with the Top Models showing by default.
3. Click on the View button in any row to View the Goal. You can use the navigation bar to move between Goals.
Results. You have a Goal in your database. It’s in Preparing status, so it’s not quite ready for use yet. It may not be perfect for you, so you can modify it in the next step.
WARNING(S): (none)
NOTE(S): (none)
10.2.2 Modify and Activate the Goal
Preconditions. You have a Goal in your database that you need to modify and activate. This may be because you have cloned a Goal.
Procedure.
1. View the Goal in the Goal list, View screen, or Edit screen.
2. Click Edit to edit the Goal.
a. You may want to change the name, description, add a subject.
b. From the Pictures tab, you can add pictures.
10.3 Create a Custom Goal (Client)
Preconditions. You have a Goal defined (or at least identified)
Procedure.
1. Open the Add a Goal page (from either your Start Center or the List Goals page.
2. Select the Create tab.
3. Fill in the required fields and Save your data.
4. Once you have filled
Results. You have a Goal in your database.
WARNING(S): Things to be cautious of when performing this task.
NOTE(S): Other important aspects or implications of this task.
10.4 Edit a Goal (Client)
Trigger. (1) You just created the Goal and you need to add more information, or (2) something about the goal changed, or (3) the Goal’s review period has passed and you need to check it,
Procedure.
1. Find the Goal in the Goals List and View the Goal.
2. Click Edit to edit the Goal.
3. Make any needed changes and press Save.
10.5 Add Projects to a Goal (Client)
Trigger. (1) You’re still building the Goal and it needs Projects to achieve it, (2) the need or desire for a new Project for the Goal has become apparent.
Procedure.
1. Find the Goal in the Goals List and View the Goal.
2. Click on the Projects tab.
3. Review the Projects.
4. To add a Project, click Add a Project and refer to the Add a Project Use Case herein.
10.6 Monitor, Review and Work on Your Goals (Client)
Preconditions. You want to check on your Goal progress and work on Goals that need attention.
Procedure.
1. Open your Goals list.
2. Review the Goal summary to see the Projects linked to the Goal and the progress on each Project.
3. To find Goals you are still Preparing, filter for Status of Preparing. These are Goals that still need work:
a. Continue to add information, Projects, pictures, etc.
b. When you are ready, Activate the Goal:
i. Open the View Goal page, select Actions, and select Activate.
10.7 What’s the Difference Between ‘Preparing’ and ‘Active’ Goals?
There’s not a lot of difference, You can work with Goals in both states. ‘Preparing’ just tells you that you are still working on defining the Goal (that’s not the same as working on achieving it). On the other hand, ‘Completed’ Goals don’t show by default in your Goals list or in your ‘pick lists’ for new Projects.
10.8 Complete a Goal (Client)
Preconditions. You believe a Goal is achieved and you don’t need to continue any projects to sustain it. (For example, “Increase my Home Value by $100,000”).
Procedure.
4. Open your Goals list.
5. Review the Goal summary to see the Projects linked to the Goal and the progress on each Project.
6. For any Goal that you feel has been achieved, View the Goal.
7. Click Actions.
8. Click Complete.
11 Use Cases for Projects
Once you have a Goal, you’ll want to create one or more Projects to execute for achieving the Goal.
11.1 Add a Shared Project (Client)
See the same topic for Goals above, but with changes:
1. (TO BE IMPLEMENTED) The projects lists may also be filtered for ‘recently cloned goals’. This allows a client to quickly locate and clone any projects linked to a goal they’ve just cloned. In most cases, sellers who offer shared goals will also offer projects to complete them, so a client can quickly add any linked projects as well.
11.1.1 Find and Clone a Shared Project
See the same topic for Goals above.
11.1.2 Modify and Activate the Project
See the same topic for Goals above.
11.2 Create a Custom Project (Client)
See the same topic for Goals above.
11.3 Edit a Project (Client)
See the same topic for Goals above.
11.4 Add Needs to a Project (Client)
$FINISH$
See the same topic for Goals above.
11.5 Monitor, Review and Work on Your Projects (Client)
See the same topic for Goals above.
11.6 What’s the Difference Between ‘Preparing’ and ‘Active’ Projects?
See the same topic for Goals above.
11.7 Complete a Project (Client)
See the same topic for Goals above.
12 Use Cases for Profiles
Now let’s step back and talk about Profiles. When creating a Project, you may realize that a Profile is needed.
12.1 Add a Shared Profile (Client)
See the same topic for Goals above, but with a few small changes.
12.1.1 Find and Clone a Shared Profile
See the same topic for Goals above.
12.1.2 Modify and Activate the Profile
$FINISH$
See the same topic for Goals above.
12.2 Create a Custom Profile (Client)
See the same topic for Goals above.
12.3 Edit a Profile (Client)
See the same topic for Goals above.
12.4 Add Projects to a Profile (Client)
$FINISH$
See the same topic for Goals above.
12.5 Monitor, Review and Work on Your Profiles (Client)
See the same topic for Goals above.
12.6 What’s the Difference Between ‘Preparing’ and ‘Active’ Profiles?
See the same topic for Goals above.
12.7 Complete a Profile (Client)
See the same topic for Goals above.
13 Use Cases for Needs
(CONTINUE)
14 Use Cases for Offers and Assets
(CONTINUE)
15 Common Use Cases for Multiple Entity Types
15.1 Create a Model Entity
(MOVE THIS UP TO THE COMMON FIELDS DESCRIPTION:
Whenever you clone an entity or create a new core entity, it is created as a “Real” entity. That is, you’re really going to use it for a specific purpose. … model
You can convert one of your
15.2 Convert a Model Back to a Real Entity
15.3 Share an Entity (Client)
Sharing an entity makes it available for others to clone for their own use.
Sharing works for the core entities: Goals, Profiles, Projects, and Needs.
When you share an Entity, if it isn’t already a model, it will be converted to one.
Preconditions. You have created an entity that you think could be valuable to others,,,
Procedure.
Postconditions.
15.4 Unshare an Entity (Client)
16
Use Cases for Application Administrators
(MOVE THIS SECTION COMPLETELY TO THE ADMINISTRATOR’S
GUIDE)
16.1
Managing Users (System Access)
16.2
How to Impersonate for Testing and Learning
16.3
How to Standardize Custom Areas and Types
16.4
How to Change Value Lists in the Database
16.5
How to Set Facility-wide Options
$FINISH$:
17 Putting it All Together
18 FAQs
We currently have no Frequently Asked Questions (FAQs).
Question:
Answer:
19 Appendix: Common Fields
These common fields are on many of the core entities and on some non-core entities. They almost always mean the same thing and work the same way on all entities.
|
Field: |
Meaning |
Notes |
|
Id |
The unique identifier for an entity |
|
|
Member |
Usually, who owns this record |
|
|
|
|
|
|
Display Scope |
Who can see this record? |
|
|
Instance Type |
Is it Real (actually in use) or a Model (a template to clone and maybe share with others) or a Test record.
For Maps and MapSets, there are also Following types.
|
|
|
|
|
|
|
Main Picture |
Almost every entity can have a Main Picture and more pictures. |
|
|
|
|
|
|
Area |
An Area is generally a ‘sector’ such as a business sector, a product sector, a service sector |
* Apparel * Home improvement * Food & Drink |
|
Sub Area |
|
|
|
Area Tags |
|
|
|
|
|
|
|
Type |
Type depends on the entity. For example, Projects can be Ongoing or Completable/Finite. |
|
|
Sub Type |
(Usually not used) |
|
|
Type Tags |
|
|
|
|
|
|
|
Seq Num |
This helps you order your records. |
|
|
|
|
|
|
Subject Name |
This is the name of the person or thing that the Entity refers to. |
* Joanne * David * Rav 4 * 320 Sycamore St. |
|
Folder |
Many entities can be placed in folders that you define. |
|
|
Class1 |
Some entities can fit in standard classes. |
|
|
Class2 |
Some entities can fit in standard classes (another class). |
|
|
|
|
|
|
Code |
Some entities have a unique code to refer to them by |
|
|
Name |
Almost every entity has a Name |
|
|
Descr |
Almost every entity can have a Description |
|
|
Tags |
Almost every entity can have Tags |
|
|
|
|
|
|
Notes |
Almost every entity can have Notes |
|
|
Summary |
Some entities have a summary |
|
|
Journal |
Most entities have a Journal of changes. |
|
|
Status |
Common statuses are Preparing, Active, OnHold, Cancelled, Completed, |
|
|
Created |
When the record was created. |
|
|
Creator |
Who created the record. |
|
|
Updated |
When the record was last updated. |
|
|
Updater |
Who last updated the record. |
|
|
Reviewed |
When the record was last reviewed. |
|
|
Reviewer |
Who last reviewed the record. |
|
|
Quality |
How good is the record data? This is useful while the record is still being prepared, or if it’s been reviewed – either formally or informally – and found to need improvement. |
|
|
Quality Notes |
Any notes on the current quality of the record. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
20 Appendix: Use Case Template (Author)
(The document author may use this template to create new Use Case topics.)
· Trigger.
· Preconditions.
· Procedure.
· Results.
· WARNING(S): Things to be cautious of when performing this task.
NOTE(S): Other important aspects or implications of this task.
(THIS DOCUMENT IS STILL IN EARLY DEVELOPMENT)