Engineer Usability - Rules #3509
Description
Overview
A key aspect of successfully participating in competitions like FHE and FSAE is ensuring that our car complies with their rules. This initiative aims to integrate competition rules within FinishLine and simplify the rule compliance process via an interactive rules dashboard.
Stakeholders
Product Stakeholder: Trip Brown, @naishahmistry, Parth Kabra
Software Stakeholder: @Peyton-McKee, Sean Walker, @chpy04
Reference Users: Max Boone, Ethan Herrell, Abby Speckhals
User Story
- As an engineering lead, I want to be able to upload competition rule PDFs to FinishLine so that I can view them in a more intuitive manner and have easy access to them.
- As an E-Board member or engineering lead, I want to be able to assign rules to specific teams and projects so that I can easily identify which rules should be followed when I am working on the car.
- As an engineering lead/member, I want to be able to update/view the status of a specific rule's compliance in a project and see the history of its compliance so that I can ensure that we are on track to successfully participate at competition.
- As an engineering lead, I want to be able to view which rules are assigned to a specific team and which rules are generally assigned/unassigned to ensure that we are following all the necessary rules and identify any rules that might have been missed.
Success Metrics
The success of the Rules Dashboard will be evident when engineering leadership and team members can effectively use FinishLine to manage various rulesets and interact with them throughout the season to ensure compliance. This includes activating the appropriate rulesets for each competition, assigning rules to individual teams, using the Project Rules Dashboard to check-off rules as the car is built, and reviewing history to confirm accuracy.
Rollout Plan
This feature is projected to complete the design process by April 25, 2025 and will be released to the development team in August 2025. E-Board and select engineering leads will be asked to test this feature in January 2026. This feature is expected to be fully adopted by the start of the construction of the car after the 2025-2026 season.
Out of Scope
While there were no immediate out-of-scope qualities about this project, some future enhancements based on user feedback could include adding notes to rules and being able to flag a rule for design issues/importance.
Background / Context
Over the past couple of years, NER has increased the number of competitions that it participates in, with the team going to its first FSAE competition in 2024. Each competition has its own set of extensive rules that the car needs to comply with in order to participate. These documents are often long, dense, confusing to navigate, and vary slightly year-to-year. Currently, engineers use spreadsheets and the original competition PDFs to ensure that we are following all the rules for each project.
To make rule compliance more efficient and centralize this growing amount of data as our team grows older and participates in more competitions, we are implementing a Rules Tab and a Project Rules Dashboard in FinishLine. This will enable users to effectively manage all competition rulesets and individual rules files in a more digestible format and support them in actively checking rule compliance for their team's projects.
Acceptance Criteria & Mock-ups
Setting Up Rules
To accommodate all of the functionality for streamlining the rules compliance process, a "Rules" tab will be added to the sidebar. This tab can only be accessed by E-Board, heads, and leads. When a user clicks on this tab for the first time, they will see the following screen that shows an empty table to host the different rulesets for various competitions.
To add a new ruleset, users can click the "Add Ruleset" button at the bottom right corner of the screen to launch the following modal.
After the new ruleset has been created, they table should be populated with the dedicated rulesets for each competition. In this example, two rulesets for FHE and FSAE have been initialized.
- Note: When initialized, the "Last Updated" date should default to the date of creation and the number of revisions should be 0. In this example, it shows 2 revisions because of the examples given in the remainder of the user flow.
If the user clicks on "View Ruleset", they will be led to the following table that contains all of the versions of the rules that exist for that competition.
- Note: When initialized, this table should be contain no data (similar to the initial Rules page).
- Note: Only one file can be marked as active to be applied to all FinishLine projects. In order to make a new file active, the user must uncheck the existing active file in the "Active?" column and then check the appropriate ruleset.
To add a new file/revision, the user can click on the "Add New Ruleset" button in the bottom right corner to launch the following model, which will ask for the file, the name that it should be referred to as, the car that the file applies to, and whether it should be the considered as the active set of rules that appear across FinishLine.
Once a file is uploaded to FinishLine, it should be parsed and the hierarchy of rules and connections should be displayed in in the format shown in the following screens. In order to edit rules in case of improper parsing or assign rules to a specific team, the user can click on the "Edit/Assign Rules" button for the appropriate file. Clicking on this will default to the screen below where they can perform CRUD functions on rule sections and individual rules.
- Users should be able to use the breadcrumbs at the top left corner of the screen to navigate back to previous pages (Rules chart, Ruleset charts, etc.)
- Users can assign rules by first selecting the team that they want to assign rules to in the left column and then selecting specific rule sections (to select all rules under that rule section) or individual rules. Users should be able to assign rules to/switch between multiple teams by selecting a different team in the left column. Selected rules will be indicated in red. To deselect, users can click on the selected rule again and it will revert to the gray background.
In order to add a whole rule section at the highest level of the hierarchy (same level as General Regulations, Administrative Regulations, etc.), users can click on the "Add Rule Section" button at the bottom right corner of the screen to launch the modal below.
To add a rule section or rule under an existing rule section, users can navigate to the rule section that they want to add it under and click the plus icon. Selecting "Add Rule Section" or "Add Rule" will open the appropriate modal and submitting the modal will add that data on the immediate next layer of the hierarchy. For example, click on the plus icon at the "Driver" level and adding a new rule section will place the new rule section at the same layer as the "Suspension" section under "Suspension and Steering".
- Note: This is a dynamic modal where the first two fields are required, but the third field is optional and will have multiple fields potentially added in order to find the appropriate rule. Please refer to the "Add Rule" under the "Rules Dashboard (Projects)" section for more information on how it should function. Also note that the referenced rule must already exist through the parsing or be manually added before referencing it when adding a new rule.
In order to delete a rule section or individual rule, users can click on the negate icon located in that rule section or rule's row. That will launch the confirmation pop-up below.
In order to edit an existing rule section or rule, users can click on the pencil icon located in that rule section or rule's row to turn that row into a text box. They can then click the "Save" button at the end of the row to save the updated text.
Rules Dashboard (Team/General)
In order to view the rules, Users can click on the "View Rules" button for the file under the ruleset that they want (ex. FSAE Original Version). This will lead them to the following page (default to "Team View" tab) where they can see the breakdown of rules the in the following hierarchy: primary rule categories (highest level in competition documents) that contain rules assigned to the team and rules not assigned to their team -> individual team projects and individual rules not assigned to projects -> individual rules assigned to projects.
- Individual rules will be assigned to specific projects using the Rules Dashboard on individual project pages. Refer to "Rules Dashboard (FinishLine Projects)" below.
- If this page is viewed before any rules are assigned to individual projects, then the second layer in the hierarchy would be removed, and it would show all rules under a rule category assigned to a team and all rules not assigned to a team.
- If a user clicks on "Unassigned Rules - Unassigned to Team", it should then replicate the hierarchy shown in the General View underneath it, but only using rules not assigned to the team.
If there is a rule that references another rule code, then there should be an additional layer to the hierarchy to display the referenced rule. An example of this in the "Team View" breakdown is below, but this concept should be applied to Rules Dashboards ("Team View", "General View", and on Project pages).
If a user would like to view or interact with the rules in a easily digestible manner, they can click on the "General View" tab, which displays the entire competition document/file in a structured, interactive hierarchy.
Rules Dashboard (FinishLine Projects)
To ensure that each FinishLine project complies with competition rules, a "Rules" tab will be added to each project where all members can see the progress towards satisfying rule requirements. There will be subtabs for each ruleset to simultaneously track compliance progress for each competition.
- This example has rules already added to the project. When first landing on this page, there should be no content.
Project leads/managers and E-Board will have dropdown access to mark an individual rule as complete or incomplete. A rule category/section will only be marked as "Complete" when all individual rules under that section are marked as complete.
Once a project's status has been changed at least once, it will have an information icon at the right-most edge of its row that is visible to all members. Clicking on the that icon will launch the "History" modal below, which shows the change log of that individual rule's compliance status in reverse chronological order.
The examples above show rules that have already been added to a project. To add rules to a project, users can click on the "Add Rule" button in the bottom right corner, which will launch the modal below. It is a dynamic modal that will only pull from the rules assigned to the team that the project is assigned to. This means that the first field will remain constant by asking them which rule category they want to access (ex. General Regulations), but then it will prompt the user with asking them to select sub-sections under that rule category until they reach a level under which there are individual rules. All the available rule categories, sub-sections, and individual rule options will be pulled from the list of rules assigned to the team via the Rules tab.
-
When a rule is added, the completion of all the associated rule sections and the individual rule should be marked as "Review"/"Incomplete".
-
To allow users to add multiple rules from a sub-section, they can click on the "Add Rule" button to create a new dropdown above the button to input a new rule. To remove a rule they added, they can click on the negate icon.
Metadata
Metadata
Assignees
Type
Projects
Status