Ruth Fuchss - The Right Tool for the Job  🔗 **Source:** [Ruth Fuchss - The Right Tool for the Job](https://www.youtube.com/watch?v=X1gvtMsA2Dc) > [!note]+ Document Notes > tags: [technical-writing, documentation-tools, docs-as-code] > author: Ruth Fuchss > source: Write the Docs Conference > reference: https://www.youtube.com/watch?v=X1gvtMsA2Dc > date created: 2024-12-19 14:30 > > # 🏷️ Title: The Right Tool for the Job - Documentation Tooling Decision Framework > <!-- deep-read:sections start --> ## 🧰 Action Inbox - [H1] Identify non-negotiables before tool selection — critical requirements like PDF output #documentation-strategy - [H2] Categorize tools by type to avoid apples-to-oranges comparisons — markup, engines, editors, delivery #tool-evaluation - [H3] Consider team expertise and company culture when choosing docs-as-code vs CCMS — stakeholder analysis #team-management ## 🧭 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 - [Video Source](https://www.youtube.com/watch?v=X1gvtMsA2Dc) ## 📝 Summary - Ruth Fuchss presents a framework for selecting documentation tools when modernizing from legacy systems - Key insight: Avoid comparing incompatible tool categories by first understanding tool taxonomy - Critical success factor: Identify non-negotiable requirements early to guide decision-making - Primary choice: Docs-as-code vs CCMS methodology, then select specific tools within chosen approach - Real-world application: Hardware company transitioning from Word/SharePoint to modern toolchain ## 📖 Main Content Ruth Fuchss, a computational linguist turned technical writer, addresses the overwhelming challenge of selecting documentation tools when modernizing legacy systems. Drawing from experience at IBM, Nordic Semiconductor, Canonical, and Atronica, she presents a systematic approach to tool evaluation. The core problem stems from the vast array of available tools and the tendency to compare incompatible categories. Fuchss categorizes documentation tools into six types: markup languages (Markdown, XML), transformation engines (Sphinx, DITA-OT), editors (VS Code, specialized XML editors), delivery platforms (Read the Docs, wikis), storage systems (Git, SharePoint), and content frameworks (Diátaxis, DITA). The fundamental decision involves choosing between docs-as-code methodology (using developer tools and workflows for documentation) versus Content and Component Management Systems (CCMS). This choice depends on team expertise, company culture, and maintenance capabilities rather than technical features alone. Key evaluation criteria include team composition, required skill sets, content consistency needs, reuse requirements, output formats, infrastructure constraints, and budget considerations. The speaker emphasizes identifying "non-negotiables" - requirements that cannot be compromised - early in the decision process. ## 🗒️ Notes #### ⏱️ [00:00](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=0) — [H1] Speaker Introduction and Context - Key idea: Ruth Fuchss brings diverse experience across hardware and software documentation - Evidence: "I've written both hardware documentation and software documentation in different setups" #### ⏱️ [02:30](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=150) — [H1] The Tool Selection Challenge - Key idea: Hardware companies typically use outdated documentation approaches - Evidence: "Word files in design files they're stored in SharePoint... all reuse was done by just copying stuff from one file and copying it into another" #### ⏱️ [04:15](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=255) — [H2] Documentation Tool Taxonomy - Key idea: Tools fall into distinct categories that must be understood before comparison - Evidence: "gets a little bit more manageable when you try to actually categorize these tools" #### ⏱️ [06:45](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=405) — [H2] Avoiding Apples-to-Oranges Comparisons - Key idea: Many tool comparisons are fundamentally invalid due to category mismatches - Evidence: "it took me a while to realize that this is not an alternative because you can totally do DITA in the docs-as-code approach" #### ⏱️ [08:20](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=500) — [H1] Docs-as-Code vs CCMS Decision Framework - Key idea: The methodology choice is foundational and limits subsequent tool options - Evidence: "the docs methodologies... are really a bit a decision on a different level" #### ⏱️ [10:30](https://www.YouTube.com/watch?v=X1gvtMsA2Dc?t=630) — [H2] Docs-as-Code Characteristics - Key idea: Uses developer tools and workflows for documentation management - Evidence: "you would use the same tools that you either are using for code or could be using for code for your documentation as well" #### ⏱️ [12:15](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=735) — [H2] CCMS Characteristics - Key idea: Specialized documentation tools with streamlined workflows - Evidence: "specialized tool that is actually made for documentation purposes... lets you focus on the content instead of the actual tooling" #### ⏱️ [14:00](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=840) — [H1] Identifying Non-Negotiables - Key idea: Critical requirements must be identified before tool evaluation begins - Evidence: "PDF support... prevented me from kind of going blindly for my favorite tool because that would have been Sphinx" #### ⏱️ [16:45](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1005) — [H2] Team and Contributor Analysis - Key idea: Understanding who writes and contributes to documentation shapes tool selection - Evidence: "developers were willing to contribute but they could not contribute mainly because they would always mess up the formatting of the word files" #### ⏱️ [19:30](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1170) — [H2] Skill Set Considerations - Key idea: Team technical expertise significantly impacts tool viability - Evidence: "software developers they pretty much started converting their internal docs to AsciiDoc when I first mentioned that" #### ⏱️ [22:10](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1330) — [H2] Maintenance and Support Requirements - Key idea: Consider available expertise for tool maintenance across different technologies - Evidence: "Sphinx is based on Python... AsciiDoc is based on Ruby... DITA that's based on XSLT, good luck finding somebody" #### ⏱️ [25:20](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1520) — [H2] Content Consistency vs Flexibility - Key idea: Balance between enforced consistency and content adaptability - Evidence: "DITA might be exactly the right tool for you... quite rigid and you need to force your content into this structure" #### ⏱️ [28:15](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1695) — [H2] Content Reuse and Advanced Features - Key idea: Advanced reuse capabilities require specific tool features - Evidence: "conditional text or variables... even plain markdown cannot really do that" #### ⏱️ [31:00](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1860) — [H2] Migration and Implementation Strategy - Key idea: Consider existing content and migration approach in tool selection - Evidence: "with pandoc I can convert word documents to AsciiDoc... without much pain" #### ⏱️ [33:45](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=2025) — [H1] Future-Proofing and Tool Switching - Key idea: Plan for potential tool changes and ensure migration paths exist - Evidence: "moving our documentation to AsciiDoc now... if in a couple of years we decide that we want to go for the CCMS approach... we can still do so" ## 📚 References - [Ruth Fuchss - The Right Tool for the Job](https://www.youtube.com/watch?v=X1gvtMsA2Dc) - [Write the Docs Conference](https://www.writethedocs.org/) ## 🗣️ Paraphrase - Documentation tool selection requires systematic categorization to avoid invalid comparisons between different tool types - The choice between docs-as-code and CCMS methodologies is foundational and should be made based on team expertise and company culture - Identifying non-negotiable requirements early prevents wasted effort evaluating unsuitable tools ## 📰 Newsletter 🔧 **Choosing the Right Documentation Tools: A Framework for Decision-Making** Selecting documentation tools can feel overwhelming with hundreds of options available. Ruth Fuchss from Atronica shared a systematic approach at Write the Docs that can save teams from costly mistakes. **The key insight**: Stop comparing apples to oranges. Tools fall into distinct categories - markup languages, transformation engines, editors, delivery platforms, storage systems, and content frameworks. Understanding these categories prevents invalid comparisons. **Start with methodology**: Choose between docs-as-code (using developer workflows) or CCMS (specialized documentation systems) based on your team's skills and company culture, not just features. **Identify non-negotiables early**: Requirements like PDF output, specific integrations, or accessibility needs should guide your evaluation from the start. This framework helps teams make informed decisions while keeping migration paths open for future changes. Resources: [Write the Docs](https://www.writethedocs.org/), [Documentation Tools Comparison](https://github.com/topics/documentation-tools), [Docs-as-Code Guide](https://www.writethedocs.org/guide/docs-as-code/) ## ✅ Action Items #### DevRel - Developer advocacy: Create comparison matrices for documentation tools used by developer communities - Education: Develop workshops on documentation toolchain selection for technical teams - Developer experience: Evaluate current documentation tools against developer workflow integration - Developer marketing: Promote docs-as-code approaches in developer-focused content - Community management: Survey community preferences for documentation formats and tools #### OSPO - Policy & Governance: Establish criteria for documentation tool evaluation in open source projects - License Compliance: Review documentation tool licenses for compliance requirements - Security Management: Assess security implications of different documentation toolchains - Software Inventory: Catalog documentation tools and their dependencies across projects - Developer Support: Provide guidance on selecting appropriate documentation approaches - Community Engagement: Support upstream documentation tool projects with funding or contributions - Strategic Alignment: Align documentation tool choices with broader open source strategy #### Community - Maintainers: Provide templates for documentation tool evaluation and selection - Contributors: Create onboarding materials for different documentation workflows - Sponsors: Fund development of open source documentation tools and integrations - Ecosystem: Facilitate cross-project sharing of documentation toolchain experiences #### WordPress - Core: Evaluate current documentation toolchain against user contribution barriers - Documentation: Assess DevHub/HelpHub tool requirements and migration paths - Community: Develop documentation tool recommendations for local communities - Training: Create curricula covering documentation tool selection and implementation - Design: Establish design tokens and style guides compatible with multiple output formats - Polyglots: Ensure documentation tools support internationalization workflows - Accessibility: Audit documentation tools for WCAG compliance and screen reader compatibility - Meta: Standardize documentation toolchains across WordPress.org properties ## 🧪 Hypotheses - Teams with strong developer skills will achieve better outcomes with docs-as-code approaches than traditional documentation tools - Organizations with mixed technical skill levels will experience higher adoption rates with CCMS solutions despite higher costs - Documentation quality improves when tool selection is driven by content requirements rather than technical preferences - Migration costs from legacy documentation systems are lower when using format-agnostic intermediate formats ### 📊 Methodology - Survey documentation teams before and after tool migrations to measure productivity and satisfaction changes - Analyze commit frequency and contributor diversity in docs-as-code versus CCMS environments - Compare content reuse patterns and maintenance overhead across different tool categories - Measure time-to-contribution for new team members across different documentation workflows ### ❓ Questions - How do documentation tool choices impact long-term content sustainability and maintenance burden? - What metrics best predict successful adoption of docs-as-code versus CCMS approaches? - How can organizations balance the flexibility of docs-as-code with the accessibility of traditional editing interfaces? ### 🔮 Future Research - Comparative analysis of documentation tool total cost of ownership including migration and training costs - Investigation of hybrid approaches combining docs-as-code workflows with CCMS accessibility features - Development of automated tool recommendation systems based on organizational characteristics ### 💡 Implications - Practice: Documentation teams should invest time in systematic tool evaluation rather than selecting familiar options - Policy: Organizations need governance frameworks for documentation tool selection and standardization - Security: Documentation toolchains introduce additional attack surfaces that require security assessment - Education: Technical writers need training in both traditional and developer-oriented documentation workflows - Funding: Budget planning must account for tool migration costs, training, and ongoing maintenance expertise ### 🧠 Learning Styles Assessment Reading level estimate: 12th grade (Flesch-Kincaid) #### 👀 Visual learners - Present: Tool categorization diagrams and comparison matrices - Improve: Process flowcharts for decision-making, tool ecosystem visualizations #### 🔊 Aural learners - Present: Conference presentation format with Q&A discussion - Improve: Podcast-style deep dives on specific tool comparisons #### 🗣️ Verbal learners - Present: Clear definitions and categorizations with concrete examples - Improve: Case study narratives and analogies for different approaches #### 🧩 Kinesthetic learners - Present: Real-world implementation examples and hands-on decision framework - Improve: Interactive tool selection worksheets and evaluation checklists #### 🧠 Logical learners - Present: Systematic categorization and decision trees - Improve: Quantitative comparison metrics and ROI calculations #### 🧑‍🤝‍🧑 Social learners - Present: Conference Q&A format with community discussion - Improve: Collaborative tool evaluation sessions and peer review processes #### 🧘‍♀️ Solitary learners - Present: Individual reflection prompts and self-assessment questions - Improve: Personal decision frameworks and private evaluation worksheets #### 🌿 Naturalistic learners - Present: Ecosystem thinking about tool relationships and dependencies - Improve: Evolution narratives of documentation tool landscapes ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Clear headings and structured content organization - Improve: More detailed alt text for tool comparison diagrams #### Keyboard navigation - Present: Standard video controls and logical content flow - Improve: Keyboard shortcuts for navigating tool comparison sections #### Contrast and readability - Present: High contrast text in presentation slides - Improve: Ensure all diagrams meet contrast requirements #### Text resizing and reflow - Present: Video content scales appropriately - Improve: Provide text-based versions of all visual comparisons #### Media and captions - Present: Video with audio narration - Improve: Complete captions and transcript with speaker identification #### Forms and interactions - Present: Simple Q&A interaction format - Improve: Interactive decision tree with accessible form controls #### Standards reference - Content meets WCAG 2.2 AA for text and audio, needs improvement for complex diagrams ### 🌍 <!-- deep-read:sections end --> [[3. Resources/Readwise/Full Document Contents/Articles/Ruth Fuchss - The Right Tool for the Job|Full Document Contents]] ## Document Notes --- tags: #technical-writing #documentation-tools #docs-as-code author: Ruth Fuchss source: Write the Docs Conference reference: https://www.youtube.com/watch?v=X1gvtMsA2Dc date created: 2024-12-19 14:30 --- # 🏷️ Title: The Right Tool for the Job - Documentation Tooling Decision Framework ## 🧰 Action Inbox - [H1] Identify non-negotiables before tool selection — critical requirements like PDF output #documentation-strategy - [H2] Categorize tools by type to avoid apples-to-oranges comparisons — markup, engines, editors, delivery #tool-evaluation - [H3] Consider team expertise and company culture when choosing docs-as-code vs CCMS — stakeholder analysis #team-management ## 🧭 Table of Contents - [[#📝 Summary]] - [[#📖 Main Content]] - [[#🗒️ Notes]] - [[#📚 References]] - [[#🗣️ Paraphrase]] - [[#📰 Newsletter]] - [[#✅ Action Items]] - [[#🧪 Hypotheses]] - [[#📊 Methodology]] - [[#❓ Questions]] - [[#🔮 Future Research]] - [[#💡 Implications]] - [[#🧠 Learning Styles Assessment]] - [[#📊 Accessibility Assessment]] - [[#🌍 DEIB Assessment]] - [[#✅ Logical Validity]] - [[#🛡️ DARVO Analysis]] - [[#🎯 Conclusion]] ### 🔗 References - [Video Source](https://www.youtube.com/watch?v=X1gvtMsA2Dc) ## 📝 Summary - Ruth Fuchss presents a framework for selecting documentation tools when modernizing from legacy systems - Key insight: Avoid comparing incompatible tool categories by first understanding tool taxonomy - Critical success factor: Identify non-negotiable requirements early to guide decision-making - Primary choice: Docs-as-code vs CCMS methodology, then select specific tools within chosen approach - Real-world application: Hardware company transitioning from Word/SharePoint to modern toolchain ## 📖 Main Content Ruth Fuchss, a computational linguist turned technical writer, addresses the overwhelming challenge of selecting documentation tools when modernizing legacy systems. Drawing from experience at IBM, Nordic Semiconductor, Canonical, and Atronica, she presents a systematic approach to tool evaluation. The core problem stems from the vast array of available tools and the tendency to compare incompatible categories. Fuchss categorizes documentation tools into six types: markup languages (Markdown, XML), transformation engines (Sphinx, DITA-OT), editors (VS Code, specialized XML editors), delivery platforms (Read the Docs, wikis), storage systems (Git, SharePoint), and content frameworks (Diátaxis, DITA). The fundamental decision involves choosing between docs-as-code methodology (using developer tools and workflows for documentation) versus Content and Component Management Systems (CCMS). This choice depends on team expertise, company culture, and maintenance capabilities rather than technical features alone. Key evaluation criteria include team composition, required skill sets, content consistency needs, reuse requirements, output formats, infrastructure constraints, and budget considerations. The speaker emphasizes identifying "non-negotiables" - requirements that cannot be compromised - early in the decision process. ## 🗒️ Notes #### ⏱️ [00:00](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=0) — [H1] Speaker Introduction and Context - Key idea: Ruth Fuchss brings diverse experience across hardware and software documentation - Evidence: "I've written both hardware documentation and software documentation in different setups" #### ⏱️ [02:30](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=150) — [H1] The Tool Selection Challenge - Key idea: Hardware companies typically use outdated documentation approaches - Evidence: "Word files in design files they're stored in SharePoint... all reuse was done by just copying stuff from one file and copying it into another" #### ⏱️ [04:15](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=255) — [H2] Documentation Tool Taxonomy - Key idea: Tools fall into distinct categories that must be understood before comparison - Evidence: "gets a little bit more manageable when you try to actually categorize these tools" #### ⏱️ [06:45](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=405) — [H2] Avoiding Apples-to-Oranges Comparisons - Key idea: Many tool comparisons are fundamentally invalid due to category mismatches - Evidence: "it took me a while to realize that this is not an alternative because you can totally do DITA in the docs-as-code approach" #### ⏱️ [08:20](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=500) — [H1] Docs-as-Code vs CCMS Decision Framework - Key idea: The methodology choice is foundational and limits subsequent tool options - Evidence: "the docs methodologies... are really a bit a decision on a different level" #### ⏱️ [10:30](https://www.YouTube.com/watch?v=X1gvtMsA2Dc?t=630) — [H2] Docs-as-Code Characteristics - Key idea: Uses developer tools and workflows for documentation management - Evidence: "you would use the same tools that you either are using for code or could be using for code for your documentation as well" #### ⏱️ [12:15](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=735) — [H2] CCMS Characteristics - Key idea: Specialized documentation tools with streamlined workflows - Evidence: "specialized tool that is actually made for documentation purposes... lets you focus on the content instead of the actual tooling" #### ⏱️ [14:00](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=840) — [H1] Identifying Non-Negotiables - Key idea: Critical requirements must be identified before tool evaluation begins - Evidence: "PDF support... prevented me from kind of going blindly for my favorite tool because that would have been Sphinx" #### ⏱️ [16:45](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1005) — [H2] Team and Contributor Analysis - Key idea: Understanding who writes and contributes to documentation shapes tool selection - Evidence: "developers were willing to contribute but they could not contribute mainly because they would always mess up the formatting of the word files" #### ⏱️ [19:30](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1170) — [H2] Skill Set Considerations - Key idea: Team technical expertise significantly impacts tool viability - Evidence: "software developers they pretty much started converting their internal docs to AsciiDoc when I first mentioned that" #### ⏱️ [22:10](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1330) — [H2] Maintenance and Support Requirements - Key idea: Consider available expertise for tool maintenance across different technologies - Evidence: "Sphinx is based on Python... AsciiDoc is based on Ruby... DITA that's based on XSLT, good luck finding somebody" #### ⏱️ [25:20](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1520) — [H2] Content Consistency vs Flexibility - Key idea: Balance between enforced consistency and content adaptability - Evidence: "DITA might be exactly the right tool for you... quite rigid and you need to force your content into this structure" #### ⏱️ [28:15](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1695) — [H2] Content Reuse and Advanced Features - Key idea: Advanced reuse capabilities require specific tool features - Evidence: "conditional text or variables... even plain markdown cannot really do that" #### ⏱️ [31:00](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=1860) — [H2] Migration and Implementation Strategy - Key idea: Consider existing content and migration approach in tool selection - Evidence: "with pandoc I can convert word documents to AsciiDoc... without much pain" #### ⏱️ [33:45](https://www.youtube.com/watch?v=X1gvtMsA2Dc?t=2025) — [H1] Future-Proofing and Tool Switching - Key idea: Plan for potential tool changes and ensure migration paths exist - Evidence: "moving our documentation to AsciiDoc now... if in a couple of years we decide that we want to go for the CCMS approach... we can still do so" ## 📚 References - [Ruth Fuchss - The Right Tool for the Job](https://www.youtube.com/watch?v=X1gvtMsA2Dc) - [Write the Docs Conference](https://www.writethedocs.org/) ## 🗣️ Paraphrase - Documentation tool selection requires systematic categorization to avoid invalid comparisons between different tool types - The choice between docs-as-code and CCMS methodologies is foundational and should be made based on team expertise and company culture - Identifying non-negotiable requirements early prevents wasted effort evaluating unsuitable tools ## 📰 Newsletter 🔧 **Choosing the Right Documentation Tools: A Framework for Decision-Making** Selecting documentation tools can feel overwhelming with hundreds of options available. Ruth Fuchss from Atronica shared a systematic approach at Write the Docs that can save teams from costly mistakes. **The key insight**: Stop comparing apples to oranges. Tools fall into distinct categories - markup languages, transformation engines, editors, delivery platforms, storage systems, and content frameworks. Understanding these categories prevents invalid comparisons. **Start with methodology**: Choose between docs-as-code (using developer workflows) or CCMS (specialized documentation systems) based on your team's skills and company culture, not just features. **Identify non-negotiables early**: Requirements like PDF output, specific integrations, or accessibility needs should guide your evaluation from the start. This framework helps teams make informed decisions while keeping migration paths open for future changes. Resources: [Write the Docs](https://www.writethedocs.org/), [Documentation Tools Comparison](https://github.com/topics/documentation-tools), [Docs-as-Code Guide](https://www.writethedocs.org/guide/docs-as-code/) ## ✅ Action Items #### DevRel - Developer advocacy: Create comparison matrices for documentation tools used by developer communities - Education: Develop workshops on documentation toolchain selection for technical teams - Developer experience: Evaluate current documentation tools against developer workflow integration - Developer marketing: Promote docs-as-code approaches in developer-focused content - Community management: Survey community preferences for documentation formats and tools #### OSPO - Policy & Governance: Establish criteria for documentation tool evaluation in open source projects - License Compliance: Review documentation tool licenses for compliance requirements - Security Management: Assess security implications of different documentation toolchains - Software Inventory: Catalog documentation tools and their dependencies across projects - Developer Support: Provide guidance on selecting appropriate documentation approaches - Community Engagement: Support upstream documentation tool projects with funding or contributions - Strategic Alignment: Align documentation tool choices with broader open source strategy #### Community - Maintainers: Provide templates for documentation tool evaluation and selection - Contributors: Create onboarding materials for different documentation workflows - Sponsors: Fund development of open source documentation tools and integrations - Ecosystem: Facilitate cross-project sharing of documentation toolchain experiences #### WordPress - Core: Evaluate current documentation toolchain against user contribution barriers - Documentation: Assess DevHub/HelpHub tool requirements and migration paths - Community: Develop documentation tool recommendations for local communities - Training: Create curricula covering documentation tool selection and implementation - Design: Establish design tokens and style guides compatible with multiple output formats - Polyglots: Ensure documentation tools support internationalization workflows - Accessibility: Audit documentation tools for WCAG compliance and screen reader compatibility - Meta: Standardize documentation toolchains across WordPress.org properties ## 🧪 Hypotheses - Teams with strong developer skills will achieve better outcomes with docs-as-code approaches than traditional documentation tools - Organizations with mixed technical skill levels will experience higher adoption rates with CCMS solutions despite higher costs - Documentation quality improves when tool selection is driven by content requirements rather than technical preferences - Migration costs from legacy documentation systems are lower when using format-agnostic intermediate formats ### 📊 Methodology - Survey documentation teams before and after tool migrations to measure productivity and satisfaction changes - Analyze commit frequency and contributor diversity in docs-as-code versus CCMS environments - Compare content reuse patterns and maintenance overhead across different tool categories - Measure time-to-contribution for new team members across different documentation workflows ### ❓ Questions - How do documentation tool choices impact long-term content sustainability and maintenance burden? - What metrics best predict successful adoption of docs-as-code versus CCMS approaches? - How can organizations balance the flexibility of docs-as-code with the accessibility of traditional editing interfaces? ### 🔮 Future Research - Comparative analysis of documentation tool total cost of ownership including migration and training costs - Investigation of hybrid approaches combining docs-as-code workflows with CCMS accessibility features - Development of automated tool recommendation systems based on organizational characteristics ### 💡 Implications - Practice: Documentation teams should invest time in systematic tool evaluation rather than selecting familiar options - Policy: Organizations need governance frameworks for documentation tool selection and standardization - Security: Documentation toolchains introduce additional attack surfaces that require security assessment - Education: Technical writers need training in both traditional and developer-oriented documentation workflows - Funding: Budget planning must account for tool migration costs, training, and ongoing maintenance expertise ### 🧠 Learning Styles Assessment Reading level estimate: 12th grade (Flesch-Kincaid) #### 👀 Visual learners - Present: Tool categorization diagrams and comparison matrices - Improve: Process flowcharts for decision-making, tool ecosystem visualizations #### 🔊 Aural learners - Present: Conference presentation format with Q&A discussion - Improve: Podcast-style deep dives on specific tool comparisons #### 🗣️ Verbal learners - Present: Clear definitions and categorizations with concrete examples - Improve: Case study narratives and analogies for different approaches #### 🧩 Kinesthetic learners - Present: Real-world implementation examples and hands-on decision framework - Improve: Interactive tool selection worksheets and evaluation checklists #### 🧠 Logical learners - Present: Systematic categorization and decision trees - Improve: Quantitative comparison metrics and ROI calculations #### 🧑‍🤝‍🧑 Social learners - Present: Conference Q&A format with community discussion - Improve: Collaborative tool evaluation sessions and peer review processes #### 🧘‍♀️ Solitary learners - Present: Individual reflection prompts and self-assessment questions - Improve: Personal decision frameworks and private evaluation worksheets #### 🌿 Naturalistic learners - Present: Ecosystem thinking about tool relationships and dependencies - Improve: Evolution narratives of documentation tool landscapes ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Clear headings and structured content organization - Improve: More detailed alt text for tool comparison diagrams #### Keyboard navigation - Present: Standard video controls and logical content flow - Improve: Keyboard shortcuts for navigating tool comparison sections #### Contrast and readability - Present: High contrast text in presentation slides - Improve: Ensure all diagrams meet contrast requirements #### Text resizing and reflow - Present: Video content scales appropriately - Improve: Provide text-based versions of all visual comparisons #### Media and captions - Present: Video with audio narration - Improve: Complete captions and transcript with speaker identification #### Forms and interactions - Present: Simple Q&A interaction format - Improve: Interactive decision tree with accessible form controls #### Standards reference - Content meets WCAG 2.2 AA for text and audio, needs improvement for complex diagrams ### 🌍 ## Highlights - already gave a bit about my background. So, I've written both hardware documentation and software documentation in different setups. I started actually working in a data CMS. then later in a more or less homegrown docs uh as code data approach even though at that time docs as code wasn't really a term that was used so much but it's pretty much what we set up and and worked with then software documentation mostly in doxygen at first and then swings later and then ([View Highlight](https://read.readwise.io/read/01k9czqgnj8k5xgjkn8rf44scr)) - Tags: 👻 ai highlighted - right tool to use for that? And how do I know this is the right tool? First question now is what is actually a tool or what do I mean when I speak about a tool here now because there's so many documentation tools out there. Here's just like a brain dump by no way exhaustive just a list of tools that seems very overwhelming. So if you look at that and try to pick the right tool for yourself or for the documentation that you're trying to ([View Highlight](https://read.readwise.io/read/01k9czqgns6dt0v4eb1a1paymw)) - Tags: 👻 ai highlighted - Then going a little bit in a different direction now up to now we mostly talked about how you actually write your documentation like well not physically but digitally but you know what I mean. Um then there's also the question how do you structure your content and there are some content frameworks that you can use for that like dataxis or also data. DA I marked in green here because it's not only a content framework it's at the same time a syntax so it would be both ([View Highlight](https://read.readwise.io/read/01k9czqgp72qaw75dyxrdjrvmp)) - Tags: 👻 ai highlighted - also do it in your documentation. So you can customize a lot of things there. But of course that comes with uh really high complexity or it can depending on how you set it up. The CCMS on the other hand is a specialized tool that is actually made for documentation purposes. So you're not reusing the stuff that that actually is made for code, but you're also using it for documentation. But this one is really specific for documentation. And it's ([View Highlight](https://read.readwise.io/read/01k9czqgqgfwm0nrtz5g8pp3fz)) - Tags: 👻 ai highlighted - usually a bit of a black box. So you don't really know or you don't need to know at least what is happening behind the scenes. Um but you just you just use it and it's just made for what you are supposed to do. You can do some tweaks of course, but you don't need to have a lot of configuration to get it working. So, it's really streamlined for documentation work. Uh, lets you focus on the content instead of the the actual tooling. So, you don't really need to ([View Highlight](https://read.readwise.io/read/01k9czqgrqp9j14bppmwa4gdkp)) - Tags: 👻 ai highlighted - definitely. And I still don't really have that. I know that we have a lot of documentation, but also putting it all into the same system is going to make it a lot easier to actually get an overview over this documentation, but having a bunch of word files everywhere makes exactly that part very difficult to get a full overview over everything that there is. >> Okay, I I do think that's all the time we have for questions, but uh now we can go ahead and break for lunch. And again, ([View Highlight](https://read.readwise.io/read/01k9czqgz9n1xww7keyq0nsbm7)) - Tags: 👻 ai highlighted