Proposal to change the user documentation workflow 🔗 **Source:** [Proposal to change the user documentation workflow](https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/) > [!note]+ Document Notes > tags: [documentation, workflow, wordpress] > author: Make WordPress Documentation > source: make.wordpress.org > reference: [https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/] > date created: 2025-12-03 00:00 > > # 🏷️ Title: Proposal to change the user documentation workflow > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - Include links cited in or relevant to the article. ## 📝 Summary - What happened: The Docs team analyzes its current multi-stage GitHub-based workflow and proposes simplifying it so user docs are ready on WordPress release day. - Why it matters: User documentation often lags releases; users see outdated or inconsistent HelpHub content. - Key stakeholders: Docs team, release squads, reviewers, plugin/theme authors, and end users. - Risks and tradeoffs: Less pre-publication review could briefly increase errors; relies on a smaller, accountable writing team. - Bottom line: Write directly in WordPress, schedule for release day, minimize pre-release reviews, and simplify GitHub tracking. ## 📖 Main Content - The current workflow uses a GitHub project with 13 status columns to represent multiple review stages, split between Dev Notes and user docs. Items move slowly across “Needs 1st Review,” “Needs 2nd Review,” and similar columns. - Drafts are typically written in Google Docs after a “Source of Truth” article exists. They often wait more than a week for a first review and again for a second review. Sometimes the second reviewer publishes; other times articles wait weeks, so releases ship with outdated docs and require follow-up. - This creates a backlog, release-order confusion (e.g., updating docs 6.4 → 6.6 → 6.5), and inconsistent user experiences when people report outdated content. - For WordPress 6.9, the team tried a different approach: writing HelpHub documentation directly in WordPress and scheduling it for release day. GitHub issues still tracked work, but reviews moved to after publication. - Based on that experience, the article recommends: skipping most pre-release review stages, forming a small dedicated writing team per release, treating pre-publish reviews as optional if someone is available, scheduling completed articles for release day, performing second reviews post-publication with corrections as needed, and simplifying the GitHub project template by removing unnecessary review columns. - The core idea is to optimize for timely, “good-enough” release-day documentation with strong accountability and iterative improvement afterward, instead of waiting for perfection before publishing. ### 🗒️ Notes - Current GitHub project has 13 status columns; several are variants of “Needs X review” which slow progress. - Drafts begin only after a Source of Truth article is available, creating built-in lag. - Use of Google Docs adds another layer before content reaches WordPress. - Long waits for both first and second reviews are common; no strict SLA is described. - Publication responsibility is ambiguous: sometimes the second reviewer publishes, sometimes not. - Backlog grows and release-order updates become jumbled, confusing both contributors and users. - WordPress 6.9’s experiment: write directly in WordPress, schedule for release day, but still open GitHub issues per article for tracking. - Accountability is maintained via GitHub, but publication is not blocked on reviews. - Reviews shift to a post-publication step, treating HelpHub like living documentation. - Proposed recommendations: - Skip most review stages before release. - Create a small, focused writing team for each release. - Make pre-publish reviews optional, not a bottleneck. - Schedule completed docs to publish on release day. - Run second reviews after publishing and correct in-place. - Reduce GitHub project complexity by collapsing review columns. - Underlying assumption: timeliness and continuity of doc updates matter more than multi-stage pre-publication polish. ## 📚 References - Proposal to change the user documentation workflow (original article): https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/ - WordPress Documentation Team: https://make.wordpress.org/docs/ - WordPress Core releases overview: https://wordpress.org/about/roadmap/ ## 🗣️ Paraphrase - Paragraph A paraphrase: The Docs team currently uses a complex, multi-column GitHub workflow with several review stages, which slows user documentation and often leaves it unfinished on release day. - Paragraph B paraphrase: After testing a simpler approach for WordPress 6.9—writing directly in WordPress and scheduling content for release day—the team proposes making this the norm, reducing pre-release reviews and simplifying GitHub tracking. ## 📰 Newsletter The Docs team is rethinking how WordPress user documentation ships with core releases. Instead of long queues in GitHub and Google Docs, the proposal is to write directly in WordPress, schedule for release day, and clean up afterward through focused reviews. This could mean fresher HelpHub content for every major release, less contributor frustration, and clearer expectations. Follow the Docs team’s work and learn how to help at https://make.wordpress.org/docs/. ## ✅ Action Items #### DevRel - Clarify messaging that HelpHub is “release-day accurate, continuously refined.” - Prepare demos/workshops on the new docs workflow for contributor days. - Create example issue templates and checklists for release-writing teams. - Track metrics: time from feature merge to docs published; backlog size. #### OSPO - Document contribution and review policies for user documentation within broader open source governance. - Ensure license and attribution requirements for documentation sources (e.g., screenshots, external quotes) are clear. - Align security and disclosure policies with how security-related docs are updated post-release. - Maintain an inventory of critical docs tied to compliance or security expectations. #### Community - Run documentation sprints around each major release using the new workflow. - Offer “first-time docs contributor” pairing during release cycles. - Encourage sponsors and agencies to allocate time to join release writing teams. - Practice cross-project drills: how plugin and theme docs align with core changes. #### WordPress - Core: Integrate docs readiness checks into release criteria (e.g., critical feature docs scheduled). - Core Performance: Ensure performance-related features include clear user-facing docs on tradeoffs. - Core AI: Document any AI-powered features with responsible use guidance and clear limitations. - Core Program Team: Add docs workflow checkpoints to release retrospectives. - Mobile: Align app help content with HelpHub updates. - Playground: Provide a sandbox example for docs contributors to test instructions safely. - Community: Add “docs workflow” segments to meetup and WordCamp programs. - Training: Build lesson plans that teach the new docs workflow and GitHub usage. - Marketing: Coordinate campaigns highlighting that docs are ready on release day. - Support: Feed common support issues back into post-release documentation improvements. - Design: Standardize docs layouts and patterns to keep content changes easy and consistent. - Documentation: Implement the proposed workflow, simplify GitHub boards, maintain style guide. - Photos: Provide up-to-date screenshots and media packs per release for docs writers. - TV: Capture short screencasts that complement written docs for new features. - Polyglots: Plan translation sprints once English docs are published on release day. - Accessibility: Ensure new docs follow accessibility guidelines and include descriptions for UI changes. - Meta: Adjust .org tooling to support scheduling, tracking, and surfacing new docs on release day. - CLI: Keep WP-CLI docs aligned with core feature documentation. - Hosting: Coordinate messaging so hosts point users to the latest HelpHub content. - Tide: Encourage plugin authors to update their docs in line with core changes and scoring. - Openverse: Update docs when media search or integration flows change. - Themes: Encourage theme authors to link to updated HelpHub articles instead of duplicating guidance. - Plugins: Make plugin review communication point to best-practice documentation examples. #### The WPOCC - Programs: Fund dedicated release-docs fellows per cycle. - Projects: Support documentation workflow experiments and publish case studies. - Funding experiments: Pilot microgrants for release-specific documentation efforts. ### FAIR - Technical independence: Encourage local export/backups of docs for provenance and reproducibility. - Policies and covenants: Make funding for docs transparent and time-bound per release. - Productized governance artifacts: Turn the proposed workflow into a documented charter and RACI for release docs. ## 🧪 Hypotheses - Simplifying the docs workflow and skipping most pre-release review stages will reduce the backlog of unfinished documentation per release. - Writing directly in WordPress and scheduling for release day will improve the proportion of features with up-to-date docs at launch. - A small, dedicated release writing team will generate more consistent and timely docs than a large, loosely coordinated contributor pool. - Post-publication reviews will not significantly decrease documentation quality compared to multi-stage pre-publication reviews. ### 📊 Methodology - Compare historical release data (pre-change) with future releases: backlog size, time-to-publish from “Source of Truth,” and percentage of features with docs on release day. - Run contributor surveys on clarity, satisfaction, and perceived friction before and after workflow changes. - Sample HelpHub articles for quality (accuracy, clarity, style compliance) across both workflows using a rubric. - Track user support tickets and forum posts about outdated docs to see if they decline with the new workflow. ### ❓ Questions - What is the minimum acceptable level of pre-release review for critical user docs? - How large should a “small” release writing team be to cover all major features? - Which GitHub columns are truly necessary for accountability without blocking work? - How can we keep translations close to release day while shifting reviews post-publication? ### 🔮 Future Research - Explore automation (bots/dashboards) to highlight features lacking docs as a release approaches. - Investigate how docs workflow changes affect contributor recruitment and retention. - Study similar documentation workflows in other large OSS projects for transferable practices. ### 💡 Implications - Practice: Docs teams may prioritize speed and iteration over multi-stage pre-publication polish. - Policy: Release checklists may explicitly treat user docs as a release criterion. - Security: Faster updates mean security-related docs can be corrected or expanded quickly post-release. - Education: Training materials need to mirror the new workflow so new contributors ramp up smoothly. - Funding: Sponsors might fund release-specific documentation teams rather than ongoing generic docs work. ### 🧠 Learning Styles Assessment - Reading level estimate: Approximately B2/C1 (upper intermediate/advanced) using a Flesch-like lens—short sentences, but many workflow and process terms assume contributor familiarity. #### 👀 Visual learners - Present: Implicit mental model of a multi-column board; some stepwise descriptions. - Improve: Add diagrams of the old vs. proposed workflows, with timelines and column names. #### 🔊 Aural learners - Present: None mentioned. - Improve: Provide a short audio summary of the proposal and its rationale. #### 🗣️ Verbal learners - Present: Clear descriptions of problems and recommendations in text; repeated key concepts. - Improve: Add concrete examples of issue cards moving through the new workflow. #### 🧩 Kinesthetic learners - Present: Implied tasks (write in WordPress, create GitHub issues). - Improve: Offer a step-by-step checklist or small “practice” doc task following the new workflow. #### 🧠 Logical learners - Present: Cause-effect chain from workflow complexity to delays; structured recommendations. - Improve: Add metrics, timelines, and before/after comparisons. #### 🧑‍🤝‍🧑 Social learners - Present: Emphasis on small writing team and reviewers. - Improve: Suggest standard rituals (weekly release-docs standups, pairing sessions). #### 🧘‍♀️ Solitary learners - Present: Post gives enough detail to reflect individually. - Improve: Add self-check questions for contributors to assess where they fit in the process. #### 🌿 Naturalistic learners - Present: None. - Improve: Use ecosystem metaphors (releases as seasons; docs as habitat updates) to explain continuous improvement. ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Standard Make/WP.org layout typically provides headings and landmarks. - Improve: Ensure headings in the proposal and resulting docs guide screen reader users clearly. #### Keyboard navigation - Present: Core WP.org theme generally supports keyboard navigation. - Improve: Confirm all controls on docs and GitHub boards are reachable and focus-visible. #### Contrast and readability - Present: WP.org generally meets contrast standards. - Improve: Validate contrast on any workflow diagrams or screenshots added later. #### Text resizing and reflow - Present: Responsive theme likely supports zoom and reflow. - Improve: Ensure any new workflow visuals reflow and remain legible at 200% zoom and beyond. #### Media and captions - Present: Article is text-based. - Improve: Provide transcripts and captions for any future screencasts explaining the workflow. #### Forms and interactions - Present: Limited to standard site navigation. - Improve: Ensure forms used in contributor onboarding or workflow tools are accessible with clear labels and errors. #### Standards reference - Map identified gaps against WCAG 2.2 AA criteria for documentation pages and related tools. ### 🌍 DEIB Assessment #### Cultural breadth - Present: Global relevance (WordPress community) but not explicitly foregrounded. - Improve: Highlight that the workflow should work across time zones and languages. #### Inclusive language - Present: Neutral, process-focused language; low jargon for experienced contributors. - Improve: Add glossaries or quick definitions for newcomers unfamiliar with “HelpHub,” “Dev Notes,” etc. #### Neurodiversity support - Present: Reasonably structured headings and lists. - Improve: Add more chunked sections, clear steps, and visual aids to reduce cognitive load. #### Representation - Present: Process-focused, not person-focused. - Improve: Include examples that show varied contributor roles and backgrounds. #### Psychological safety - Present: Tone is constructive and non-blaming. - Improve: Explicitly note that mistakes in docs can be fixed quickly and are part of the process. ### ✅ Logical Validity #### Strong reasoning - Causal reasoning: Complex multi-stage reviews → delays → outdated docs; supported by observed waits and backlogs. - Practical experiment: 6.9 workflow is used as evidence that writing directly in WordPress and scheduling works. #### Fallacies - Potential overgeneralization: Assuming the 6.9 experiment will generalize smoothly to all releases without more data. Could be strengthened by outlining limits and monitoring plans. #### Tone of voice - Calm, analytical, and collaborative; focused on improving process rather than assigning blame. ### 🛡️ DARVO Analysis - Deny: No denial of problems; the article openly acknowledges delays and backlogs. - Attack: No attacks on individuals or groups; criticism is aimed at process design. - Reverse victim/offender: None; users’ needs and contributors’ frustrations are both recognized. ## 🎯 Conclusion The article argues that the existing, review-heavy workflow for WordPress user documentation delays release-ready docs and creates backlogs. A successful 6.9 experiment suggests writing directly in WordPress, scheduling for release day, and shifting most reviews post-publication while simplifying GitHub tracking. Next steps: agree on a leaner workflow, pilot it across more releases, measure timeliness and quality, and iterate based on contributor and user feedback. ## 🧱 Refactor Appendix (append after 🎯 Conclusion) ### 📚 Literature Split Pad - Purpose: Stage Konik CEE units that become per-source Literature notes. - Split level: H3. - Include verbatim quotes under 25 words and a [view highlight] link. ### [H1] 5–10-word present-tense claim > [!quote] [Proposal to change the user documentation workflow](https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/) by [[Make WordPress Documentation]] via [[make.wordpress.org]]. Published 2025-12-02. Accessed 2025-12-03. > “This process leads to a growing backlog of unfinished documentation.” Two lines: context and use. Cite data if relevant. [view highlight](https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/#H1) #xref #articleseed ID:rw_[MISSING] ### [H2] 5–10-word present-tense claim > [!quote] [Proposal to change the user documentation workflow](https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/) > “For WordPress 6.9, the HelpHub documentation was written directly in WordPress.” Two lines: context and use. [view highlight](https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/#H2) #xref ID:rw_[MISSING] --- ### 🔖 Atomic Split Pad (Zettel Candidates) - Purpose: Promote reusable claims into Atomic notes. - Split level: H4. - Each item: one idea, present tense, specific, testable. #### [Z1] Lean docs workflow reduces release delays - Scope/condition in one line. - Pointer to page/time or dataset. - Links: [[WordPress-Documentation]] [[Workflow-Design]] #### [Z2] Post-publication reviews maintain doc quality - Scope/condition in one line. - Pointer to page/time or dataset. - Links: [[Documentation-Quality]] [[Release-Processes]] --- ### ✏️ Fleeting Queue (Extract by Selection) - Purpose: Capture quick actions or sparks for Fleeting notes. - Extraction: Select one line → “Refactor: Extract selection to new note (content only).” - Keep each line short and self-contained. - [F1] Draft a visual old-vs-new docs workflow diagram — context/https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/ #fleeting #inbox - [F2] Define metrics for docs readiness on release day — context/https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/ #fleeting #inbox - [F3] Propose contributor training on the new docs workflow — context/https://make.wordpress.org/docs/2025/12/02/proposal-to-change-the-user-documentation-workflow/ #fleeting #inbox --- <!-- deep-read:sections end -->