Skip to content

Glossary Process

Glossary Management Process

About This Process

This document outlines the standard process for managing the project glossary, including how to propose, review, approve, and maintain terminology. Following these guidelines ensures consistency and clarity in our project communication.

Overview

A well-maintained glossary is essential for effective communication between technical and business stakeholders. This process document provides a structured approach to glossary management that ensures terms are accurate, up-to-date, and useful for all team members.

Glossary Term Lifecycle

  • 1. Proposed

    Initial draft submitted for review and validation

    Actions: Create term using template, submit for review

  • 2. Approved

    Validated and accepted by the team

    Actions: Update status, add to appropriate glossary

  • 3. Updated

    Revised with new or clarified information

    Actions: Update content, record changes in version history

  • 4. Deprecated

    No longer in active use but kept for reference

    Actions: Update status, add deprecation notice

  • 5. Superseded

    Replaced by a newer term or definition

    Actions: Update status, link to replacement term

Process Steps

Creating a New Term

  1. Identify Need: Recognize when a term requires formal definition
  2. Check Existing Terms: Verify the term doesn't already exist in the glossary
  3. Use Template: Copy the glossary term template
  4. Draft Definition: Create clear, concise definition with necessary context
  5. Add Metadata: Include all required metadata (category, status, etc.)
  6. Provide Examples: Add usage examples to clarify meaning
  7. Submit for Review: Share with relevant stakeholders for feedback

Reviewing Terms

  1. Verify Accuracy: Ensure the definition is technically and conceptually correct
  2. Check Completeness: Confirm all required sections are completed
  3. Assess Clarity: Evaluate if the definition is understandable by the intended audience
  4. Consider Context: Verify the term fits within the project's context
  5. Provide Feedback: Offer constructive suggestions for improvement
  6. Approve or Request Changes: Formally approve or request specific revisions

Maintaining the Glossary

  1. Regular Reviews: Schedule periodic reviews of the entire glossary
  2. Update Outdated Terms: Revise definitions that no longer reflect current usage
  3. Deprecate Unused Terms: Mark terms that are no longer relevant
  4. Add Cross-References: Link related terms to improve navigation
  5. Version Control: Maintain a history of changes to each term
  6. Solicit Feedback: Regularly ask for input from glossary users

Roles and Responsibilities

Glossary Maintainer

  • Oversees the glossary management process
  • Reviews and approves term submissions
  • Ensures consistency across all terms
  • Schedules regular glossary reviews

Term Contributors

  • Identify terms that need definition
  • Draft new term definitions
  • Suggest updates to existing terms
  • Participate in term reviews

Stakeholders

  • Provide domain expertise for term validation
  • Review terms relevant to their area
  • Suggest new terms from their domain
  • Use the glossary in their communications

Best Practices

Writing Definitions

Definition Guidelines

  • Start with a clear, concise statement of what the term means
  • Use plain language whenever possible
  • Avoid circular definitions (defining a term using the term itself)
  • Include the context in which the term is used
  • Differentiate from similar or related terms

Organizing Terms

  • Group related terms by category or domain
  • Use consistent formatting across all terms
  • Maintain alphabetical order within categories
  • Include cross-references to related terms
  • Tag terms with relevant metadata for filtering

Communication

  • Announce new and updated terms to the team
  • Reference the glossary in project documentation
  • Encourage team members to consult the glossary
  • Solicit feedback on term clarity and usefulness
  • Use terms consistently in all project communications

FAQ

Who can propose new terms?

Anyone on the project team can propose new terms. Simply follow the process outlined in the "Creating a New Term" section.

How often should the glossary be updated?

The glossary should be updated whenever new terms emerge or existing terms change. Additionally, schedule a comprehensive review quarterly.

What if there are disagreements about a definition?

Disagreements should be resolved through discussion with relevant stakeholders. The Glossary Maintainer makes the final decision if consensus cannot be reached.

Can terms be removed from the glossary?

Terms are typically not removed but rather marked as "Deprecated" or "Superseded" to maintain historical context.

How do I know if a term needs to be in the glossary?

Consider adding a term if it is specific to the project, has a specialized meaning in the project context, or is frequently misunderstood.