mivical

Help Documentation for Technical Debt Tracker

Introduction

Welcome to Technical Debt Tracker, an innovative Jira Forge application designed to effectively track and manage technical debt in your software projects. This tool provides comprehensive insights into your project’s technical debt, enabling you to make informed decisions for better software health and sustainability.

Installation

Step-by-Step Guide:

  1. Navigate to the Atlassian Marketplace and search for “Technical Debt Tracker.”
  2. Click on the app listing and select “Add to Jira” or “Install.”
  3. Follow the prompts to integrate the app with your Jira instance.

Prerequisites

In order to use the Technical Debt Tracker you must have “liabilities” and “assets” and history. You need to have the following:

  1. A project with at least one month of issues
  2. A basic understanding of JQL
  3. We recommend using due dates on issues for more accurate scores

Getting Started

Creating a New Workbook

After installing Technical Debt Tracker, the initial step in setting up your environment is to create a Workbook. The Workbook acts as a template for categorizing your technical debt items and defining how they are managed within your Jira project.

How to Create a Workbook

  1. Access the Workbook Section: In the Technical Debt Tracker interface, locate the Workbook drop-down menu.
  2. Initiate Workbook Creation: Click the “+” icon next to the drop-down menu to open the creation dialog.
  1. Fill Out Workbook Details:
  • Name: Enter a unique name for your Workbook. This name will be used to identify different Workbooks within your project.
  • Optimal Resolution Days: Specify the ideal number of days in which issues should be resolved. These are bugs and technical debt issues that don’t have a due date.
  • Algorithm: Select an algorithm from the drop-down list that will be used to calculate the technical debt scores. Default is a good one to start with.
  • Liability Query (JQL): Input a Jira Query Language (JQL) statement to identify liabilities such as bugs or technical debt items. For example, “project = KEY and type IN (Bug, “Tech Debt”)”.
  • Asset Query (JQL): Enter a JQL statement to find assets, which are completed features contributing positively to your project. An example might be “project = KEY and type IN (Story)”.
  1. Save the Workbook: After completing all the fields, click the ‘Submit’ button to save your new Workbook. If you wish to discard the changes, you can click ‘Cancel’ to close the dialog without saving.

How to Create a Statement

Statements are essential in the Technical Debt Tracker as they encapsulate all the data required to calculate your technical debt score for a given period. Creating a statement is a straightforward process that helps you track and manage technical debt over time.

How to Create a Statement

  1. Select Your Workbook: Within the app interface, start by selecting the workbook you want to work with from the drop-down menu.
  2. Navigate to Statements: Click on the “Statements” section in the navigation menu.
  3. Create Monthly Statements: For each month that your project has been active, you’ll need to create a new statement. This ensures that you have a comprehensive view of your technical debt’s progression.
  4. Generate a New Statement:
    • To create a statement for a specific month, select the month from the provided options and then click on the “Generate Statement” button. This will create a statement with all the necessary data for that month.
    • If you want to generate statements for multiple months, you can use the “Play” button adjacent to the month drop-down. This will automate the creation of statements for each selected period.
  5. Review and Save: After a statement is generated, review the calculated data to ensure accuracy. Save the statement to preserve the record of your technical debt analysis for that month.

By regularly creating statements, you maintain an updated and actionable record of your technical debt, which is invaluable for strategic planning and debt resolution efforts.


Based on the screenshot provided, it appears that after generating a statement in your Technical Debt Tracker app, users will see a comprehensive view that includes several key metrics. Here’s a guide section that you can include in your documentation to explain what users should expect to see after creating a statement:

Understanding Your Score

Once you have successfully created and generated a statement for a given period, the Technical Debt Tracker app will display a detailed summary of your technical debt assessment. There are various sections in you statement:

  • Score Indicator: A dynamic gauge showing the technical debt score, which quantifies the current state of your technical debt. A higher score indicates a healthier project state.
  • Letter Grade: Corresponding to the score, the letter grade provides a quick, easily digestible assessment of your technical debt status, similar to an academic grade.
  • Descriptor: A qualitative descriptor (e.g., ‘Good’, ‘Fair’, ‘Poor’) offers a textual representation of your score’s meaning.
  • Details: The name of the workbook associated with the current statement, statement date, start and end, last revision and revision number
  • Liabilities Table: A current statement month and last statement month view of the liabilities in the statement including the change month-to-month.
  • Assets Table: A current statement month and last statement month view of the assets in the statement including the change month-to-month.
  • Ratio Table: A current statement month and last statement month view of the any ratios in the statement including the change month-to-month.

With this information, you can track the progression of your technical debt over time and understand the impact of your resolution efforts. Regularly reviewing your statements will help you to stay informed about the health of your software development and maintain control over your technical debt.

Troubleshooting

  • Common Issues and Solutions:
  • Problem: Technical Debt Tracker is not updating scores.
  • Solution: Ensure all JQL queries are correctly set in the workbook. Check if all relevant issues are updated in Jira.
  • FAQs:
  • Q: How often are the technical debt scores updated?
  • A: Scores are updated monthly based on issue resolution and changes.

Support

If you encounter any issues or have questions, please reach out to our support team: