> ## Documentation Index > Fetch the complete documentation index at: https://docs.stage3.app/llms.txt > Use this file to discover all available pages before exploring further. # Collaboration Best Practices > Tips and guidelines for effectively collaborating on process documentation ## Why Collaboration Matters The best process documentation isn't created by one person in isolation. It's built collaboratively by the people who actually do the work, maintained by those who own the outcomes, and improved continuously based on real experience. Effective collaboration makes your documentation more accurate, more useful, and more likely to be followed. Think of process documentation as a living team asset, not a static document someone created once and filed away. ## Core Collaboration Principles Capture how work actually happens, not how you wish it happened People who do the work should help document it Let people know when processes change and why Improve processes based on experience, don't wait for perfection ## Building Collaborative Culture **The problem:** Documentation becomes one person's responsibility, and they become a bottleneck. **The solution:** * Share Edit permission with multiple trusted team members * Encourage everyone to contribute improvements * Recognize and thank people who improve documentation * Make documentation updates part of regular work, not a separate task **Example:** "When you figure out a better way to do something, update the process documentation right away. Don't wait for someone else to do it." **The problem:** People are afraid to question processes or suggest changes. **The solution:** * Use Comment permission liberally to invite feedback * Respond positively to all suggestions, even if you don't implement them * Thank people for pointing out issues * Create a culture where "dumb questions" don't exist **Example:** "Great question! I'll add clarification to Step 3 to address this. Thanks for pointing it out." **The problem:** Processes change but documentation doesn't, making it useless. **The solution:** * Update documentation immediately when processes change * Review processes quarterly even if they haven't changed * Assign process owners responsible for keeping things current * Make documentation updates part of change management **Example:** Before implementing a new tool or changing a procedure, schedule time to update the documentation. **The problem:** Contributing to documentation is complicated or intimidating. **The solution:** * Use simple, intuitive tools * Provide templates and examples * Make the editing process straightforward * Lower the bar for "good enough" contributions **Example:** "Don't worry about making it perfect. Add what you know, and we'll refine it together." ## Communication Guidelines ### When to Comment vs. When to Edit Asking questions Proposing significant changes Disagreeing with current approach Starting discussions Pointing out problems you're unsure how to fix Requesting clarification **Example:** "I think Step 4 should come before Step 3 because you need X before you can do Y. What does everyone think?" Fixing typos and grammar Updating broken links Adding missing information you're sure about Implementing agreed-upon changes Updating outdated information Adding screenshots or examples **Example:** Just fix the typo or update the link. No need to comment first. ### Writing Effective Comments Point to exactly what you're commenting on. Don't make vague statements. **Good:** "In Step 3, the form link is broken. Here's the updated link: \[URL]" **Bad:** "Something is wrong" Explain why something matters or how it affects work. **Good:** "When we skip Step 2, customers get confused and call support. Can we make this step required?" **Bad:** "We should change Step 2" Don't just identify problems; propose fixes when possible. **Good:** "The approval threshold is outdated. Current policy requires VP approval for $10K+, not $5K+ as shown. I'll update if that's correct." **Bad:** "This is wrong" Use @mentions to notify people who can help or need to know. **Good:** "@ProcessOwner can you clarify the approval chain? @TeamLead I think this affects your team too" **Bad:** Comment without notifying anyone, then wonder why it wasn't addressed Frame feedback positively, focusing on improvement. **Good:** "This guide is helpful! One addition: can we include what to do if the system times out?" **Bad:** "This guide doesn't cover enough scenarios" ## Version Control Etiquette If someone is actively editing, wait your turn or coordinate with them. **Check:** * Who's currently viewing/editing * If major updates are in progress * Whether changes will conflict **Better approach:** Comment on what you want to change and let the current editor incorporate it. Don't leave the editor open for hours with unsaved changes. **Do:** * Save every few minutes * Complete your edits in one session when possible * Save before switching to other tasks **Why:** Prevents lost work and reduces conflicts with other editors. Before making sweeping changes, let the team know. **Methods:** * Add a comment explaining what you're about to do * Message the team via email or chat * Discuss in a meeting first * Get buy-in from stakeholders **Example:** "I'm reorganizing the activities section tomorrow morning to match our new workflow. Let me know if you have concerns." For significant updates, note what changed and why. **Options:** * Add a comment after making changes * Update the revision history section * Post in your team chat * Send a summary email **Example:** "Updated the sales process to reflect our new CRM. Main changes: Steps 2-4 now use Salesforce instead of spreadsheets. Old screenshots replaced. @SalesTeam please review." ## Avoiding Conflicts Schedule documentation work when others aren't editing. Announce when you're making large updates. Assign different people to different sections or categories to avoid overlap. Discuss major changes in comments before implementing to build consensus. Each process should have a clear owner who has final say on conflicts. ## Handling Disagreements What to do when team members disagree about how a process should work: Make sure everyone's viewpoint is heard and understood. Different teams or roles might have valid but different experiences. What result are you trying to achieve? Often disagreements are about methods, not goals. Find common ground in the desired outcome. If available, check metrics, error rates, time spent, or customer feedback. Data can settle debates objectively. When in doubt, try one approach, measure results, and adjust. Document the experiment and timeline. If consensus can't be reached, the process owner makes the final call. Document the decision and rationale. **Remember:** Disagreements about processes are usually healthy. They mean people care about doing things right. Handle them professionally and use them as opportunities to improve. ## Roles and Responsibilities **Responsibilities:** * Ensure process documentation stays current * Review and respond to comments * Coordinate major updates * Make final decisions on disputes * Monitor process effectiveness * Schedule regular reviews **Key principle:** Facilitate, don't dictate. Get input from the team. **Responsibilities:** * Make improvements as you notice needs * Keep information accurate based on real work * Communicate major changes * Respect the process owner's final decisions * Help onboard new team members **Key principle:** You're a maintainer, not the owner. Collaborate, don't compete. **Responsibilities:** * Point out errors or gaps * Ask clarifying questions * Suggest improvements * Share insights from experience * Be constructive and specific **Key principle:** Your feedback improves the process. Don't hesitate to share. **Responsibilities:** * Follow documented procedures * Ask questions when unclear (via comments if you have permission, or to the process owner) * Report issues or outdated information * Provide feedback on usability **Key principle:** You're not just consuming documentation; you're validating it. ## Meeting Practices ### Documentation Review Meetings **Purpose:** Quick check that critical processes are still accurate **Agenda:** * Review comment threads * Discuss any reported issues * Confirm no major changes needed * Assign action items **Duration:** 15-30 minutes **Attendees:** Process owners and key contributors **Purpose:** Thorough review of process effectiveness **Agenda:** * Walk through the entire process * Identify improvements based on experience * Review KPIs and metrics * Update documentation * Plan major changes **Duration:** 1-2 hours **Attendees:** Entire team that uses the process **Purpose:** Major restructuring or complete rewrites **Agenda:** * Evaluate if process is still relevant * Consider complete redesign if needed * Incorporate lessons from the year * Set goals for the coming year * Update all documentation **Duration:** Half-day workshop **Attendees:** All stakeholders ## Onboarding New Team Members Help new people contribute effectively: Start new team members with View permission. Upgrade to Comment after they're familiar with the process. Consider Edit permission after they've demonstrated understanding. Show them: * Where to find processes * How to navigate documentation * How to add comments * Who to ask for help Don't assume they'll figure it out. New people see processes with fresh eyes. Their "dumb questions" often reveal unclear documentation. Create a safe environment for questioning. Pair new team members with experienced contributors who can guide them. This builds collaboration habits early. When someone makes their first improvement to documentation, acknowledge it. This reinforces that collaboration is valued. ## Tools and Techniques Create templates for common documentation types so everyone follows the same structure Use consistent screenshot tools and annotation styles for professional-looking guides Record complex procedures as videos to complement written instructions Maintain a glossary of terms so everyone uses consistent language ## Red Flags to Watch For **Documentation Drift** Documentation no longer matches reality. People ignore it because it's outdated. **Fix:** Schedule regular reviews and update immediately when processes change. **Single Point of Failure** Only one person knows how to update documentation or has Edit permission. **Fix:** Share Edit permission with at least 2-3 people. Cross-train on documentation maintenance. **Comment Graveyards** Lots of comments but no responses or action. People stop commenting because nothing happens. **Fix:** Process owners must respond to every comment, even if just to say "we're looking into this." **Edit Wars** Two or more people keep changing the same content back and forth. **Fix:** Use comments to discuss the issue. Process owner makes final decision. Document the rationale. **Documentation Debt** Processes change faster than documentation. The backlog of needed updates grows. **Fix:** Make documentation updates part of implementing changes, not a follow-up task. ## Continuous Improvement Ask team members what's working and what's not. Use surveys, meetings, or one-on-ones. If multiple people ask the same question, the documentation needs improvement. Add clarification where confusion occurs. Track KPIs like completion time, error rates, or quality scores. Poor metrics might indicate documentation issues. When documentation changes lead to better outcomes, share the success. This motivates continued collaboration. Real-world use reveals what works and what doesn't. Continuously refine based on actual experience. ## Quick Reference: Dos and Don'ts Update documentation when you learn better ways Ask questions when something is unclear Provide specific, constructive feedback Thank people for their contributions Communicate before making major changes Document reality, not aspirations Respond to comments promptly Share credit for improvements Wait for someone else to fix issues you notice Make vague complaints without suggestions Delete others' work without discussion Leave comments unanswered for weeks Hoard Edit permission unnecessarily Make major changes without communicating Criticize people for asking questions Let documentation become outdated ## Measuring Collaboration Success Good collaboration leads to: Process docs reflect how work actually happens today Multiple team members regularly contribute and improve People find answers in documentation instead of asking Process metrics improve as documentation improves ## Next Steps Learn how to share processes with your team Understand access control for collaboration Measure process performance collaboratively