- Table of contents
- Redmine Documentation Standards
Redmine Documentation Standards¶
The following document establishes the minimum standards that the project team is expected to adhere to while using the redmine ticketing system. Any issues regarding the ticketing system standards that are not addressed by this document should be handled with common sense, and if still in doubt, consult the rest of the team. The tickets can be made more quickly using the ticket templates.
Ticket Workflow¶
An item is added to the queue under the Product Backlog tracker, these will be large tasks that are not well defined (e.g. “Establish legal requirements” or “Academic deliverables Week 4”). The items in the Product Backlog will then be groomed into several smaller subtasks that are achievable within a sprint. The sprints will then be assigned to team members with an estimated time and due date.
Common ticket fields¶
The fields listed below are shared by all tickets regardless of tracker category. It describes the information expected of each field.
Tracker: The category that the ticket falls under: Bug, Feature, Support, Product Backlog, Sprint and Management. (Discussed in further detail below). It is important to select the appropriate tracker type for the issue to ensure team members can easily distinguish the subject matter of the ticket.
Subject: Kept brief while using relevant terms. Best practice is to include the name associated with the area the ticket addresses. Large amounts of detail should be established in the description section and not within the subject heading.
Description: The ticket description must provide relevant and detailed information. The description of a ticket must be relevant to the subject, do not introduce different issues inside the description if it does not correlate with the subject title. If a separate issue exists that holds relation with the subject, determine whether it should be made a sub-ticket of the previous issue. The structure for a description varies based on the tracker category which is detailed below.
Status:
New - Newly generated ticket, which has not been assigned.
In Progress - Ticket is currently being worked on.
Resolved - Team member believes the issue is completed.
Feedback - Used when the team member working on the ticket requires feedback from the client.
Closed - Client acknowledges the resolution is to their satisfaction.
Rejected - The ticket issue has been refused, typically applies to features. Requires documentation as to the why the ticket was rejected.
Priority:
Low - Are of minimum concern and can be postponed. Priority must be reviewed weekly.
Normal - Must be worked on weekly, can take several weeks if required.
High - Must be resolved within the week.
Urgent - Must be resolved within a 48-hour window.
Immediate - Must be resolved within a 24-hour window and is a primary concern of the entire team.
Assignee (Optional): Used for allocation of an issue to relevant team member.
Start Date: When work on the ticket will commence.
Due Date: When the work on the ticket is expected to be delivered.
Estimated Time: An approximation of the work hours required.
% Done: Updated as the work progresses to completion.
Parent Task (Optional): Used to link sub-tickets to their parent task.
Tracker Categories¶
The following explains the required layout for the ticket description for each tracker category. Below is the minimum required headings and information that each type will require.
Product Backlog: Large tasks that aren’t well defined (e.g. “Establish legal requirements”). They must be groomed and broken down into smaller and smaller tasks (sub-tickets) until each task is an actionable sprint.
Time spent grooming the Product Backlog, should ticketed against the parent ticket rather than the child sub-ticket.
Sprint: A small task that is achievable by one team member or a small task that must be completed by several / all team members.
Problem/Motivation - Describes what the sprint must achieve and why.
Proposed Resolution - Describes a way of solving the problem.
Done Definition - Clearly defines when the problem is solved.
Management: Used for documentation of internal meeting agendas and minutes, some details will be incomplete when first listed (such as the minutes, because the meeting hasn't yet taken place) and will be filled in once the meeting has happened.
Agenda Topics - Lists the topics that are to be discussed, team members can add to this list leading up to a meeting.
Meeting Information - Lists the following fields: Date and Time, Location, Duration, Meeting called by, Type of meeting, Note-taker, Attendees, Apologies.
Meeting Minutes - Lists the Discussions and Conclusions for each topic of the meeting.
Bug: An unexpected or incorrect result produced by the system.
Summary - Explain the bug in words be as specific as possible.
Steps to Reproduce - List procedure to replicate the bug. Describe with as much detail as possible.
Expected Results - Explain the application behaviour that was intended and be as specific as possible.
Actual Results - Explain the application behaviour that was experienced.
Feature: Describes functionality needed by another team member’s module. (Will typically have a priority that is high or above, as the problem is impeding development for a team member).
Problem - What is needed from the module that it currently doesn’t provide.
Motivation - Why you need the module to perform said functionality.
Relevant Technical Notes - Any notes that will assist the other team member in providing the needed functionality.
Support: Used when in the process of a sprint and assistance is required from another team member (e.g. questions on how they have implemented a module).
Problem/Motivation - What action are you trying to get the module to perform and why you need the module to perform it in relation to your sprint.
Relevant Technical Notes - Any notes that will assist the other team member in providing assistance.
Log time (Spent time)¶
Issue: The ticket number that the spent time will be logged against.
Date: The date that the work has been performed.
Hours: How many hours were spent working on the ticket.
Comment: A brief overview of the work that was performed, as well as anything of important note.
Activity: The type of work performed: design, development, documentation, discussion.
Updated by Peter Qian about 4 years ago · 1 revisions