Skip to main content

Documenting Issue Workflow

Establishing and implementing a clear, approved workflow for the documentation process within the Procedures Manual, from issue registration through solution approval.

Workflow Overview​

This workflow ensures that all troubleshooting issues are properly documented, reviewed, and approved before being added to the handbook.

Documenting Issue Workflow Chart​

Step-by-Step Process​

1. Issue Registration​

When: An issue is identified during troubleshooting or support activities.

Actions:

  • Document the issue clearly
  • Identify the issue type (Common Dynamics NAV, Intercard, or new category)
  • Note the symptoms and error messages
  • Record any temporary workarounds

Responsible: Support Staff, IT Staff, or System Administrators

2. Issue Categorization​

Categories:

  • Common Dynamics NAV Issues - Standard NAV/LS Retail problems
  • Intercard Issues - FEC Back Office System, Game Settings, iCashier
  • New Category - Issues requiring a new category (create with approval)

Responsible: Technical Team Lead

3. Reference Number Assignment​

Format: ISSUE-XXX (sequential numbering)

Process:

  • Check existing issues to determine next number
  • Assign unique reference number
  • Format: ## Problem (ISSUE-XXX)

Responsible: Technical Team Lead or Documentation Maintainer

4. Documentation Creation​

Required Sections:

  1. Problem - Clear description with reference number
  2. Symptoms - What users will see/experience
  3. Solution - Step-by-step resolution steps
  4. Prevention - How to avoid the issue (if applicable)
  5. Related Issues - Links to similar problems
  6. Additional Resources - Manuals, guides, related docs

Template Format:

## Problem (ISSUE-XXX)

[Provide a clear and concise description of the problem, including the reference number.]

## Symptoms

- [Describe the first symptom or error message.]
- [Describe the second symptom or any additional observable behavior.]

## Solution

### Step 1: [Action]
[Describe the detailed steps for this action.]

### Step 2: [Action]
[Describe the detailed steps for this action.]

## Prevention

- [Describe how to prevent this issue from happening again, if applicable.]

## Related Issues

- [Link to related issue]

## Additional Resources

- [Link to manual, guide, or other supporting documentation]

Responsible: Technical Team Lead or assigned staff

5. Technical Review​

Reviewer: Technical Team Lead

Checklist:

  • ✅ Problem is clearly described
  • ✅ Solution is accurate and complete
  • ✅ Steps are easy to follow
  • ✅ Reference number is correct
  • ✅ Links to related resources work
  • ✅ Formatting follows standards

Outcome:

  • Approved → Proceed to Head of Software review
  • Changes Required → Return to documentation creator

6. Head of Software Review​

Reviewer: Head of Software Department

Checklist:

  • ✅ Technical accuracy verified
  • ✅ Solution is approved for publication
  • ✅ No security or compliance concerns
  • ✅ Documentation quality meets standards

Outcome:

  • Approved → Proceed to publication
  • Changes Required → Return with feedback

7. Publication​

Actions:

  1. Add issue to appropriate section
  2. Update Issue Reference List in introduction page
  3. Verify all links work correctly
  4. Test documentation accessibility
  5. Commit changes to repository

Responsible: Documentation Maintainer or Technical Team Lead

Approval Authority​

StageApproverAuthority Level
Technical ReviewTechnical Team LeadContent accuracy, completeness
Final ApprovalHead of Software DepartmentPublication approval, compliance

Documentation Standards​

Reference Numbering​

  • Sequential numbering: ISSUE-001, ISSUE-002, etc.
  • Format: ## Problem (ISSUE-XXX)
  • No gaps in numbering sequence

File Naming​

  • Use kebab-case: issue-description.md
  • Be descriptive and specific
  • Match the issue title

Content Quality​

  • Clear, concise problem descriptions
  • Step-by-step solutions with numbered steps
  • Include warnings and tips where appropriate
  • Link to related resources

Formatting​

  • Use Docusaurus markdown features
  • Include InternalBanner component
  • Use proper heading hierarchy
  • Add code blocks for technical steps

Change Management​

Updating Existing Issues​

  1. Document the change reason
  2. Update the issue file
  3. Request review from Technical Team Lead
  4. Get approval from Head of Software (if significant change)
  5. Update and republish

Deprecating Issues​

  1. Mark issue as deprecated
  2. Add note explaining why
  3. Link to replacement issue (if applicable)
  4. Remove from active reference list
  5. Archive documentation

Responsibilities​

Technical Team Lead​

  • Review documentation for accuracy
  • Assign reference numbers
  • Ensure documentation standards
  • Coordinate with Head of Software

Head of Software Department​

  • Final approval authority
  • Compliance verification
  • Strategic documentation decisions

Documentation Maintainer​

  • Maintain issue reference lists
  • Ensure formatting consistency
  • Update introduction pages
  • Manage documentation repository

Support Staff / IT Staff​

  • Identify and report issues
  • Provide initial documentation
  • Test solutions before documentation

Quality Assurance​

Pre-Publication Checklist​

  • Reference number assigned and correct
  • Problem clearly described
  • Solution tested and verified
  • All steps are accurate
  • Links to resources work
  • Formatting is consistent
  • Technical review completed
  • Final approval obtained
  • Issue added to reference list
Workflow Status

This workflow is active and should be followed for all new troubleshooting documentation.

Approval Required

No documentation should be published without proper review and approval from the Head of Software Department.

Best Practice

Document issues as soon as they are resolved to ensure accuracy and completeness while details are fresh.

Last updated on by shellatomic