diff --git a/docs/access/how-to-use-and-maintain-the-tower-distillery-onboarding-guid.md b/docs/access/how-to-use-and-maintain-the-tower-distillery-onboarding-guid.md new file mode 100644 index 0000000..2c5ee84 --- /dev/null +++ b/docs/access/how-to-use-and-maintain-the-tower-distillery-onboarding-guid.md @@ -0,0 +1,212 @@ +# How to Use and Maintain the Tower Distillery Onboarding Guide + +## Overview + +This guide explains the purpose, scope, and maintenance expectations for the Tower Distillery Onboarding Guide. It is intended for internal Tower team members who onboard new colleagues, contribute to Distillery workflows, or are considering adapting the guide for external implementations. + +## Prerequisites + +- Access to the Tower Distillery Onboarding Guide (internal documentation location not specified in the source content). +- Basic familiarity with: + - The Tower Distillery and its role in building routines. + - Distyl/Tower implementations and terminology. + - Internal systems referenced in the guide (for example: QLAB, TLife, SQAR, and Distyl x T‑Mobile content), if applicable. +- Appropriate permissions to edit internal documentation. + +> Note: The exact storage location (e.g., Confluence, Notion, internal wiki) and access controls for the guide are not specified and should be confirmed with the Tower Distillery or Growth team. + +## Purpose and Intended Use + +The Tower Distillery Onboarding Guide was created to: + +1. **Shorten onboarding time** for new team members learning how to build routines in the Distillery. +2. **Democratize context** around how the Distillery works so it is accessible to everyone, not just AI Specialists (AIS) and AI Engineers (AIEs). +3. **Lighten the load** on existing team members who currently onboard new joiners. + +Early feedback from Growth leadership indicates that this guide should become a **standard resource for all new Distillery teammates**. + +The guide is also being used as a **teaching resource** (for example, in Metro Academy sessions) and will be iterated based on what is learned in those trainings. + +## How to Use the Onboarding Guide + +1. **For new Distillery team members** + - Use the guide as your primary reference for: + - Understanding Distillery concepts and workflows. + - Learning how to build and manage routines. + - Getting oriented to Tower-specific tools and processes. + - Follow the guide in sequence (if it is structured as a walkthrough) to reduce ramp-up time. + - Capture questions or gaps you encounter and share them with your manager or the Distillery documentation owner so the guide can be improved. + +2. **For managers and onboarding leads** + - Incorporate the guide into your **standard onboarding plan** for new Distillery hires and Distyl folks starting on Tower. + - Use the guide as a baseline curriculum for: + - One-on-one onboarding sessions. + - Group trainings (e.g., Metro Academy). + - Encourage new joiners to: + - Read the guide early in their onboarding. + - Refer back to it before escalating routine questions. + +3. **For existing Distillery contributors** + - Treat the guide as the **closest thing to a Distillery user manual**: + - Reference it when you need a refresher on workflows. + - Point teammates to relevant sections instead of re-explaining processes ad hoc. + - When workflows change, **update the guide promptly** to keep it accurate and reduce knowledge silos. + +## How to Maintain and Improve the Guide + +The guide is intended to be a **living document**. Everyone is encouraged to contribute. + +1. **Identify what needs updating** + - Look for: + - Outdated steps or screenshots. + - New workflows that are not yet documented. + - Tower-specific nuances that are missing or unclear. + - Pay special attention after: + - Product changes. + - Process updates. + - New implementation patterns. + +2. **Make edits directly (if you have edit access)** + - Update text to reflect current workflows. + - Replace or annotate screenshots when interfaces change. + - Add clarifying notes where new joiners have repeatedly asked questions. + +3. **Propose changes (if you do not have edit access)** + - Share suggested edits with the current documentation owner or Distillery lead. + - Include: + - The section to change. + - The proposed new wording or steps. + - Any relevant context (e.g., “this changed in release X.Y”). + +4. **Align with product documentation (if applicable)** + - There is interest in using this guide as a **base for a product docs section**: + - Consider which parts are general Distillery concepts that could be exposed to external users. + - Flag sections that are highly Tower-specific or implementation-specific. + +5. **Iterate based on training feedback** + - When the guide is used in training (e.g., Metro Academy): + - Capture questions that arise. + - Note where trainees get stuck. + - Update the guide to address those pain points. + +## Considerations for External Use + +There is active discussion about whether and how to adapt this guide for external users (e.g., customers or other implementations). + +### Content suitability + +- **Generally appropriate for external Tower users**: + - The author does not believe there is anything inherently inappropriate for external Tower users. +- **Caution for cross-customer sharing**: + - Several systems and examples are **specific and proprietary to T‑Mobile** (e.g., Distyl x T‑Mobile content, QLAB, TLife, SQAR). + - These should not be shared broadly across customers without modification. + +### Recommended sanitization steps for externalization + +If you intend to adapt the guide for external consumption: + +1. **Remove or rewrite implementation-specific sections** + - Remove the **Distyl x T‑Mobile** section. + - Replace T‑Mobile-specific workflows with generalized patterns where possible. + +2. **Scrub proprietary references** + - Remove or anonymize references to: + - QLAB + - TLife + - SQAR + - Any other internal-only systems or acronyms that are not intended for external audiences. + +3. **Update screenshots** + - Replace screenshots that: + - Contain proprietary information. + - Reveal internal-only tools, identifiers, or customer-specific data. + - Use sanitized or generic examples instead. + +4. **Segment access where needed** + - Consider a model similar to **newsletter gating**: + - Some pages visible to all implementations. + - Some pages gated to specific implementations (e.g., Tower-only). + - Work with product and implementation teams to define which pages are: + - General (safe and useful for all implementations). + - Tower-specific (more valuable internally than as general docs). + +## Important Notes and Caveats + +- **Location and ownership not specified**: + The source content does not specify: + - Where the guide is stored (e.g., Confluence, Notion, internal wiki). + - Who is the formal owner or maintainer. + - How access is controlled. + + This information should be clarified internally. + +- **Scope of content not fully described**: + The guide is described as a “Distillery user manual” and onboarding resource, but: + - The exact table of contents. + - The specific workflows covered. + - Any associated commands, URLs, or paths + are not provided in the source content. + +- **Product docs integration is exploratory**: + Using this guide as a base for in-product documentation is an idea under consideration, not a finalized plan. Coordination with product and documentation teams will be required. + +## Troubleshooting and Common Issues + +Because the original Slack thread does not list concrete issues, the following are anticipated scenarios and suggested actions: + +1. **New joiners still feel lost after reading the guide** + - Verify they: + - Have access to the latest version. + - Understand the intended reading order. + - Ask them to note: + - Which sections were confusing. + - Which questions were unanswered. + - Update the guide to address those gaps. + +2. **Content appears outdated** + - Compare the guide against current: + - Distillery workflows. + - Product UI. + - Internal systems and naming. + - If discrepancies are found: + - Log them in your team’s documentation backlog or ticketing system. + - Prioritize updates, especially for onboarding-critical sections. + +3. **Uncertainty about what can be shared externally** + - When in doubt: + - Treat all implementation-specific and customer-specific content as **internal only**. + - Consult with: + - Legal or compliance (if required). + - Product leadership. + - Implementation leads (e.g., Tower, T‑Mobile). + - Use the sanitization steps above before publishing anything externally. + +4. **Difficulty keeping docs up to date** + - Embed documentation updates into: + - Definition of Done for workflow or feature changes. + - Release checklists. + - Encourage teams to: + - Treat the guide as part of the product surface. + - Update it alongside code and configuration changes. + +## Additional Information Needed (Gaps to Clarify) + +To fully operationalize this documentation, the following details should be captured elsewhere or added in a future revision: + +- **Exact location and link** to the Tower Distillery Onboarding Guide. +- **Document owner(s)** and escalation path for: + - Approving major changes. + - Resolving content disputes. +- **Versioning and change-log process**: + - How changes are tracked. + - How new versions are communicated to the team. +- **Explicit list of sections** that are: + - Tower-specific. + - Implementation-specific (e.g., T‑Mobile). + - General and suitable for all external implementations. +- **Any related URLs, commands, or paths** used in Distillery workflows that should be documented for new users. + +Once these details are known, they should be added to this document and to the onboarding guide itself to make the process more self-service and robust. + +--- +*Source: [Original Slack thread](https://distylai.slack.com/archives/C089K6FPZHA/p1765225986584309)*