Collect changes to guided tour

Problem

The guided tour aims to lead new users through the features and functionalities of PermaplanT's Frontend. When user facing features change or get added this affects the guided tour. Currently there is no unified way to track and collect issues that implement changes impacting the guided tour.

Example: A new filter feature gets added to the frontend but because there are no clear responsibilities for updating the guided tour the new feature isn't included and users of the site don't know how to access or use the feature or miss it completely.

Constraints

  1. The process for collecting guided tour–related issues must be quick, intuitive, and require minimal additional effort from developers.
  2. The collected issues must be easily visible and accessible to the person(s) responsible for maintaining and updating the guided tour.

Assumptions

  1. The collection of issues will take some additional effort.
  2. Untracked changes will always be possible.

Solutions

Alternative A

Adding checklist item to issue templates ("Does this affect the guided tour?")

Developers mark issues impacting the guided tour by checking this new checkbox in the issue template.

Alternative B

Creating a new label "affects::guided-tour"

Developers mark issues impacting the guided tour by adding this new tag.

Alternative C

Adding dedicated section to issue templates for guided tour impacts

More indepth impact tracking by adding a new section to issue templates. Developers can give more detailed information about the guided tour impact of issues by describing how their changes might affect the guided tour.

Decision

A workflow using a combination of the above alternatives will be created and refined. This workflow will ensure the efficient tracking of issues that impact the guided tour while ensuring the concrete impacts themselves are also documented in sufficient detail. The workflow is specified in guided_tour_updates.md

Rationale

The use of a single alternative does not fully cover the requirements of the issue collection. A combined approach, defined within a clear workflow, will ensure both the systematic collection of relevant issues and the easy accessibility of the information needed by those responsible for maintaining the guided tour.

Implications

  • The workflow has to be created, refined and implemented.
  • Developers have to remember to follow the steps of the workflow.