Developer Documentation in the Age of AI  🔗 **Source:** [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) > [!note]+ Document Notes > tags: [WordPress, Documentation, AI, Developer Relations, LLM, SEO] > author: [MISSING] > source: WordPress.tv > reference: [https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/] > date created: 2025-11-10 15:30 > > # 🏷️ Title: Developer Documentation in the Age of AI > <!-- 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 - [WordPress.tv Video](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) - [VideoPress Direct Link](https://videopress.com/v/CQBhHXzU) ## 📝 Summary This WordPress.tv session explores how developer documentation must evolve in response to AI-powered coding workflows. As generative AI tools become standard in software development, the speaker argues that documentation remains critical but must be optimized for discoverability by LLMs, not just human readers. **What happened:** A WordPress community talk examining documentation strategy in the AI era, covering the evolution from SEO to "GEO" (Generative Engine Optimization), best practices for AI-friendly documentation, and the balance between comprehensive reference materials and human-crafted tutorials. **Why it matters:** With developers increasingly relying on AI assistants for code generation, platforms and plugins that fail to optimize their documentation for LLM consumption risk becoming invisible to the next generation of builders. This represents a fundamental shift in developer marketing and education strategy. **Key stakeholders:** Plugin developers, platform documentation teams, DevRel professionals, open source maintainers, WordPress core documentation contributors, and anyone responsible for developer-facing content. **Risks and tradeoffs:** Over-optimizing for AI could make documentation less useful for humans. Auto-generated reference docs may lack the context and storytelling that helps developers understand the "why" behind APIs. There's tension between comprehensive coverage and maintainability. **Bottom line:** Documentation still matters in the AI age, but the strategy must shift. Maintain fresh, structured content that search algorithms can index. Combine auto-generated API references with thoughtfully crafted guides and tutorials. Be explicit about data structures, parameters, and return values. Cross-link extensively. And remember that LLMs blend existing search with their training data, so SEO principles still apply. ## 📖 Main Content The landscape of developer education is undergoing a fundamental transformation. Every day, more code is written with the assistance of generative AI tools, from chatbots like ChatGPT and Claude to AI-infused IDEs like Cursor and GitHub Copilot. Developers increasingly rely on these tools to build functionality on existing platforms like WordPress, but this shift raises critical questions about documentation strategy. ### The Continued Value of Documentation Despite AI's capabilities, documentation remains essential because LLMs have inherent limitations. They're trained on data with cutoff dates, meaning they lack knowledge of recent features, APIs, and best practices. New information, new data, and new ways of doing things emerge constantly in the software ecosystem. For this content to reach users building on your platform, it must exist in discoverable, structured formats that both search engines and AI systems can process. The economic structures of the web are shifting, and while this evolution may be concerning to content creators, there remains significant value in publishing fresh, relevant content that AI systems can access and synthesize. The key is understanding how AI tools actually discover and use documentation. ### From SEO to GEO: The Evolution of Discovery Traditional search engine optimization (SEO) focused on helping content rank well in Google and other search engines. Now, new terms are emerging: AEO (Answer Engine Optimization), GEO (Generative Engine Optimization), and LLM-EO (Large Language Model Engine Optimization). While these acronyms sound different and have subtle distinctions, they fundamentally address the same core challenge: making content discoverable. At the end of the day, anything you create needs to be discoverable, and search remains the primary mechanism for discovery. Modern AI systems like ChatGPT and Claude don't just rely on their training data—they actively use search algorithms to find recent, relevant content and blend it into their responses. When a developer asks an LLM "How do I set up my local WooCommerce environment?", the system searches the open web, finds relevant documentation, and synthesizes it into a response with citations. This hybrid approach—combining pre-trained knowledge with real-time search—means that traditional SEO principles still matter. Your documentation needs to be findable by search algorithms for it to be useful to AI systems. ### Best Practices for AI-Friendly Documentation The speaker highlighted several key insights from the community: **Danny Sullivan's WordCamp US Talk:** Google's search liaison gave a comprehensive talk at WordCamp US about how SEO is both changing and staying the same. His core message: focus on creating useful content for humans first. If it's valuable to humans, it will be valuable to AI systems. This aligns with Google's long-standing guidance to avoid gaming the system and instead create genuinely helpful resources. **Structured Information Architecture:** While full transcripts and detailed code examples have their place, documentation should be structured for scannability and precision. Be very explicit about parameters, return values, and data structures. Tools like MCP (Model Context Protocol) demonstrate that the more concrete you can be about inputs and outputs, the better AI systems perform. **Types of Documentation:** Effective documentation ecosystems include multiple genres: - **Guides:** Higher-level content that explains philosophy, architecture, and project-level concepts - **Tutorials:** Step-by-step instructions for specific tasks, getting users from point A to point B - **Reference Documentation:** Comprehensive coverage of APIs, hooks, filters, functions—the "what" without extensive "why" ### Balancing Auto-Generation and Human Craft Reference documentation—API docs, function signatures, parameter lists—can often be auto-generated from code comments and type definitions. Tools exist for most programming languages to extract this information systematically. This is valuable and should not be skipped, as it provides the precise, structured data that LLMs need. However, the middle layer—guides and tutorials—is where human intentionality and storytelling become critical. This is where you explain not just what a function does, but when to use it, why it exists, and how it fits into broader patterns. Auto-generating tutorials rarely produces quality results because they lack the pedagogical structure and contextual understanding that makes learning effective. ### Developer-Specific Considerations When your target audience is developers specifically, there are unique considerations: **Developer Psychology:** Developers tend to be independent, self-starting, and averse to content that feels like a sales pitch. They want to dive in, experiment, and figure things out themselves. Documentation must support this learning style by providing clear, complete information without forcing them through marketing funnels. **Marketing Aversion:** Developers will quickly abandon platforms that put barriers between them and the technical information they need. Everything must be available for self-service exploration. This is especially important in the early adoption phase when developers are evaluating whether to invest time in your platform. **Progressive Disclosure:** While developers want depth available, they also benefit from progressive disclosure—starting with high-level concepts and allowing them to drill down into specifics as needed. The documentation architecture should support both quick reference and deep exploration. ### Cross-Linking and Information Architecture One of the most important but often overlooked practices is extensive cross-linking between different types of documentation. Reference docs should link to relevant tutorials. Guides should point to API references. Each piece should acknowledge and connect to the broader ecosystem of information. This cross-linking serves multiple purposes: 1. Helps human readers navigate efficiently 2. Helps search engines understand relationships between content 3. Provides context for AI systems synthesizing information from multiple sources ### Questions and Community Discussion The Q&A portion revealed ongoing tensions in documentation strategy: **Code Examples:** There's debate about how much code to include. Too much code can make documentation overwhelming and harder to maintain. But developers (and AI systems) benefit from seeing actual implementation examples, especially for complex return objects or data structures. The solution may be providing clear type definitions and schema documentation alongside selective examples. **Data Structure Documentation:** When functions return complex objects (like those from Advanced Custom Fields), it's important to document the structure explicitly. Some developers report that adding these structures as comments in their code helps AI assistants understand their intentions. This suggests documentation should include explicit schema definitions, perhaps using JSON Schema, TypeScript types, or similar formal specifications. **Maintenance Burden:** Documentation is only valuable if it stays current. Auto-generation helps with reference docs, but guides require ongoing human attention. Teams must balance comprehensiveness with maintainability, potentially prioritizing coverage of the most-used features and workflows. ## 🗒️ Notes #### ⏱️ [00:11:00](https://videopress.com/v/CQBhHXzU?at=660) Introduction - Limitations of LLMs - LLMs are limited to training data with cutoff dates - New information, features, and best practices emerge constantly - Fresh content must be discoverable to reach developers building on platforms - Economic structures of the web are shifting - Value remains in publishing relevant content for AI access #### ⏱️ [00:11:28](https://videopress.com/v/CQBhHXzU?at=688) Documentation Objectives in AI Era - AI is important but LLMs won't know everything - Documentation remains critical despite AI capabilities - Need to identify where value aligns between traditional and AI-driven approaches - Question: What are we doing now vs. what will people do next? #### ⏱️ [00:11:56](https://videopress.com/v/CQBhHXzU?at=716) From SEO to GEO - Evolution of Discovery - SEO (Search Engine Optimization) is familiar concept - New terms emerging: AEO, GEO, LLM-EO - Terms sound different but address same core challenge - Everything created needs to be discoverable - Search remains the primary discovery mechanism - LLMs use search algorithms to find recent relevant content - Example: Searching "How do I set up my local WooCommerce environment?" - LLM provides tutorial but shows websites it searched in sidebar - WooCommerce developer blog appeared in sources - Combination of LLM capabilities + open web search remains important #### ⏱️ [00:13:20](https://videopress.com/v/CQBhHXzU?at=800) Danny Sullivan's WordCamp US Talk - Attendee question: Did anyone attend WordCamp US? - Recommendation to watch Danny Sullivan's talk - Danny Sullivan works at Google - Talk covers how SEO is changing and not changing - Addresses doing things differently vs. same approaches - Important context for documentation strategy #### ⏱️ [00:13:28](https://videopress.com/v/CQBhHXzU?at=808) Core Insight - Human Value First - The most important insight from multiple sources - If content is useful to humans, it will be useful to AI - Avoid attempting to game the system - Focus on creating genuinely helpful resources - This principle applies across documentation types #### ⏱️ [00:14:36](https://videopress.com/v/CQBhHXzU?at=876) Practical Example - Local Setup Documentation - WooCommerce has local setup documentation - When asked about creating documentation pages - Can use AI to generate initial draft - Important: AI should not be generating content directly for publication - AI assists in drafting, humans ensure quality and accuracy #### ⏱️ [00:15:55](https://videopress.com/v/CQBhHXzU?at=955) Documentation Structure and Scannability - Discussion about full transcripts vs. structured content - Transcripts have value but can be overwhelming - Documentation should be structured for scannability - Users need to find specific information quickly - Balance between comprehensiveness and usability #### ⏱️ [00:21:15](https://videopress.com/v/CQBhHXzU?at=1275) Best Practices Summary - Focus on fresh, relevant content - Structure for both human and AI consumption - Be explicit about parameters and return values - Cross-link between documentation types - Maintain different genres: guides, tutorials, references - Auto-generate where possible, craft tutorials with intention #### ⏱️ [00:42:24](https://videopress.com/v/CQBhHXzU?at=2544) Developer Psychology and Marketing Aversion - Developers are independent and self-starting - Want to get through documentation on their own - Averse to anything that feels like sales tactics - If target market is developers, must be very clear - Everything must be available for self-service - Let developers be self-starting enough to invest in platform - Developers will jump off quickly if they sense marketing manipulation - Different considerations for end-user focused software #### ⏱️ [00:42:58](https://videopress.com/v/CQBhHXzU?at=2578) Q&A - Code Examples and Data Structures - Question about putting too much code in documentation - Specific concern: functions returning complex objects (e.g., ACF) - Challenge: How to make AI aware of data structures - Developer's approach: putting data structures in code comments - Makes AI assistants smarter about intentions - Question: Where to put this information in documentation? #### ⏱️ [00:43:49](https://videopress.com/v/CQBhHXzU?at=2629) Documentation Genres and Types - Different types of documentation serve different purposes - **Guides:** Higher level, philosophy, project-level concepts - **Tutorials:** Step-by-step, one specific task from A to B - Not comprehensive coverage of feature - Focused on accomplishing specific goal - **References:** Exhaustive coverage of APIs, hooks, filters - Example: WooCommerce has developer docs, REST API reference, and codex - Each type serves different use cases #### ⏱️ [00:44:23](https://videopress.com/v/CQBhHXzU?at=2663) Cross-Linking and Reference Generation - Having reference guides and cross-linking is important - Reference documentation is generally easy to auto-generate - Makes sense to find good tools for your language/platform - Should not skip the reference guide component - Middle step (guides/tutorials) requires human element - Intentionality behind guides and tutorials matters - Mix of auto-generated references and human-crafted guides #### ⏱️ [00:45:10](https://videopress.com/v/CQBhHXzU?at=2710) Explicit Parameters and MCP - Being very explicit about input/output parameters is extremely important - Example: Tools like MCP (Model Context Protocol) - The more concrete you can be about input and output, the better AI performs - Continue keeping parameters and return values updated - This helps both humans and AI systems understand your APIs ## 📚 References - [WordPress.tv - Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) - [VideoPress Direct Link](https://videopress.com/v/CQBhHXzU) - [Danny Sullivan's WordCamp US Talk](https://wordpress.tv) (specific link not provided in transcript) - [WooCommerce Developer Blog](https://developer.woocommerce.com/blog/) - [WooCommerce Developer Documentation](https://developer.woocommerce.com/) - [WooCommerce REST API Reference](https://woocommerce.github.io/woocommerce-rest-api-docs/) - [Google Search Central](https://developers.google.com/search) - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Advanced Custom Fields (ACF) - mentioned in Q&A - ChatGPT, Claude - example AI assistants mentioned - Cursor, GitHub Copilot - AI-infused IDEs mentioned ## 🗣️ Paraphrase The fundamental shift toward AI-assisted development doesn't diminish the importance of documentation—it transforms how documentation must be created and structured. While Large Language Models have impressive capabilities, they're constrained by training cutoffs and need access to current information through search mechanisms. This means traditional SEO principles remain relevant even as new concepts like Generative Engine Optimization emerge. The core insight, echoed across community experts like Google's Danny Sullivan, is straightforward: create documentation that genuinely helps humans, and it will naturally serve AI systems well. This isn't about gaming algorithms but about providing clear, structured, discoverable information. The hybrid approach modern AI systems take—blending pre-trained knowledge with real-time search of the open web—means your documentation must be findable to be useful. Documentation strategy should embrace a multi-genre approach. Auto-generate precise reference materials that define APIs, parameters, and return values with technical accuracy—this is where automation excels and AI systems benefit most from explicit structure. But preserve human authorship for guides and tutorials, where storytelling, context, and pedagogical design create understanding that transcends mere function signatures. For developer audiences specifically, documentation must respect their self-directed learning style. Developers are independent problem-solvers who quickly abandon platforms that interpose marketing friction between them and technical information. Everything must be available for self-service exploration, with progressive disclosure allowing quick reference for experts and deeper explanation for newcomers. The information architecture matters as much as the content itself. Extensive cross-linking between different documentation types helps humans navigate, helps search engines understand relationships, and provides critical context for AI systems synthesizing from multiple sources. A tutorial should link to relevant API references; a reference should point to practical guides; everything should acknowledge the broader ecosystem. As tools like the Model Context Protocol demonstrate, being explicit about data structures, inputs, and outputs significantly improves how AI systems work with your platform. When functions return complex objects, document their shape formally—consider JSON Schema, TypeScript definitions, or equivalent specifications that both humans and machines can parse reliably. The maintenance challenge remains real. Auto-generation helps with reference docs, but guides require ongoing human attention. Teams must balance comprehensiveness with sustainability, potentially prioritizing coverage of the most-used features and workflows while maintaining freshness where it matters most. Documentation is only valuable if it stays current, and currency requires sustainable processes. ## 📰 Newsletter **📚 Your Documentation Strategy Needs an AI Upgrade (But Not the Way You Think)** Hey WordPress community! 👋 If you've been wondering whether your plugin's documentation still matters now that everyone's coding with ChatGPT and Claude, I've got news: it matters more than ever, but the playbook is changing. Fresh off WordPress.tv comes a must-watch session on developer documentation in the age of AI. Spoiler alert: The robots aren't replacing your docs—they're *using* them. And if your docs aren't discoverable, your plugin might as well be invisible to the next generation of builders. Here's the thing: LLMs don't actually know everything. Shocking, right? They've got training cutoffs, which means that killer new feature you shipped last month? Totally unknown unless it's documented and discoverable on the open web. Modern AI assistants are basically really smart search engines in a trench coat—they search the web in real-time and synthesize what they find. So yes, SEO still matters. Call it GEO, call it AEO, call it whatever acronym makes your heart happy—it's all about making content findable. **The golden rule** (courtesy of Google's Danny Sullivan at WordCamp US): If it's useful to humans, it'll be useful to AI. Don't try to game the system. Just make genuinely helpful stuff. Revolutionary, I know. 😉 **Here's what your documentation stack needs:** - **Reference docs** → Auto-generate these! Your APIs, hooks, filters—all that technical precision is perfect for automation. Be super explicit about parameters and return types. Tools like MCP are proving that the more concrete you are about inputs/outputs, the better AI performs. - **Tutorials** → Keep humans in the loop here. Step-by-step guides need that pedagogical structure and context that only human authors can provide. Take developers from A to B on one specific task. - **Guides** → Philosophy, architecture, the "why" behind your design—this is where storytelling matters. AI can't generate your platform's vision. **Pro tips from the talk:** - Cross-link everything. Your reference docs should point to tutorials. Your tutorials should link to references. Help humans navigate AND give AI the relationship context it needs. - Know your audience. If you're targeting developers specifically, remember they're independent, self-starting, and will bounce immediately if your docs feel like a sales funnel. Everything must be available for self-service exploration. - Document those data structures! When your function returns a complex object (looking at you, ACF), be explicit about the schema. Some devs are already putting these in code comments to help AI assistants—imagine how much better your docs could be with formal definitions. The economics of the web are shifting, and yeah, that's unsettling. But there's still massive value in publishing fresh, relevant, well-structured content. The combination of LLM knowledge + real-time web search isn't going anywhere. So audit your docs. Are they discoverable? Structured? Up to date? Do they balance auto-generated precision with human-crafted guidance? Your future developers (and their AI assistants) will thank you. **Resources to check out:** - [Watch the full WordCamp talk](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) - [WooCommerce Developer Blog](https://developer.woocommerce.com/blog/) (mentioned as an example of discoverable docs) - [Danny Sullivan's SEO talk from WordCamp US](https://wordpress.tv) (seriously, watch this) Happy documenting! 📝✨ ## ✅ Action Items #### DevRel - **Developer advocacy:** Create presentation deck on AI-friendly documentation patterns for WordCamp circuit; measure adoption through follow-up surveys - **Education:** Host monthly office hours on documentation strategy for plugin developers; create 4-week workshop series on balancing auto-generated vs. human-crafted content - **Developer experience:** Audit WooCommerce documentation for AI discoverability; implement structured data markup on all API reference pages; measure engagement through search analytics - **Developer marketing:** Launch content campaign highlighting documentation as competitive advantage; create comparison matrix showing documentation approaches across ecosystem - **Community management:** Establish documentation review process in plugin repository guidelines; moderate #docs channel with focus on AI-readiness discussions - **Internal alignment:** Coordinate with SEO team on GEO/AEO strategies; establish feedback loop between support tickets and documentation gaps; set SLAs for documentation updates tied to release cycles - **External collaboration:** Partner with AI tool providers (Claude, ChatGPT teams) to understand how they index WordPress docs; share learnings with ecosystem - **Cross-project:** Present documentation findings at WordPress Contributor Day; collaborate with Training team on documentation best practices course #### OSPO - **Policy & Governance:** Develop documentation standards policy for projects receiving OSPO support; establish contribution guidelines for AI-generated content in docs - **License Compliance:** Review auto-generation tools for license compatibility; ensure documentation generation pipeline respects upstream licenses - **Security Management:** Establish vulnerability disclosure process that includes documentation updates; ensure security advisories reference specific doc sections - **Software Inventory:** Include documentation status in SBOM; track which components have AI-optimized docs vs. legacy formats - **Developer Support:** Create consultation hours specifically for documentation strategy; develop tooling recommendations by language/framework - **Community Engagement:** Fund documentation sprints at WordCamps; provide stipends for documentation maintainers in key ecosystem projects - **Strategic Alignment:** Include documentation quality KPIs in quarterly OKRs; executive reporting on documentation as strategic initiative; track "documentation debt" as technical debt metric #### Community - **Maintainers:** Conduct documentation roadmap clinics at Contributor Days; create governance templates for documentation team structures; establish release hygiene checklists that include docs updates - **Contributors:** Design "first documentation issue" rotation program; pair new contributors with experienced docs writers; create getting-started guide specifically for documentation contributions - **Sponsors:** Develop transparent budget proposals for documentation initiatives; define clear milestones for funded documentation projects; create impact reports showing discoverability improvements - **Ecosystem:** Organize cross-project documentation incident drills (what if major API changes?); coordinate disclosure process that includes docs updates across dependent projects #### WordPress - **Core:** Prioritize documentation for new features in 6.9 release; establish triage process for docs issues linking to support forum patterns; set performance budgets for docs site loading; define release criteria that include documentation completeness - **Core Performance:** Create profiling documentation showing before/after optimization examples; build metrics dashboard for docs site performance; establish performance bounty program for docs improvements - **Core AI:** Develop responsible AI guardrails for using AI in documentation generation; create evaluation sets for AI-generated docs quality; pilot project using LLMs to identify documentation gaps - **Core Program Team:** Establish coordination rituals between component teams and docs team; map cross-team dependencies for major initiatives; conduct retrospectives on documentation handoffs - **Mobile:** Document mobile-specific considerations for plugin developers; review app documentation for AI discoverability; improve offline documentation UX - **Playground:** Create browser-based documentation labs where developers can test examples; build reproducible bug report templates that include documentation context; develop education modules using Playground for interactive tutorials - **Community:** Create meetup presentation kits on documentation best practices; develop WordCamp documentation track playbook; establish speaker mentorship program for documentation topics - **Training:** Develop lesson plans on creating AI-friendly documentation; create learning path from basic docs writing to comprehensive documentation architecture; pilot certification program for documentation specialists - **Marketing:** Launch campaign highlighting WordPress documentation excellence; develop narrative around "documentation as developer experience"; create social editorial calendar featuring documentation wins - **Support:** Set response SLAs for documentation-related questions; identify knowledge base gaps through ticket analysis; create escalation path from support to docs team - **Design:** Conduct UX audit of developer documentation sites; develop design tokens for documentation systems; maintain research backlog on developer information-seeking behavior - **Documentation:** Close DevHub/HelpHub gaps identified in accessibility audit; implement examples-first pattern in new content; update style guide with AI-optimization guidelines - **Photos:** Maintain documentation images for common WordPress UI patterns; establish moderation guidelines for screenshot submissions; improve taxonomy for searchable image metadata - **TV:** Create submission guide specifically for documentation-related talks; improve caption quality through AI-assisted review; implement content indexing for video documentation - **Polyglots:** Coordinate translation sprints for high-impact documentation; align glossary terms across locales; track locale coverage of critical documentation - **Accessibility:** Conduct WCAG review of major documentation sites; develop documentation-specific accessibility tooling; create issues heatmap showing common accessibility problems; establish quarterly audit cadence - **Meta:** Include documentation search in .org API reliability metrics; improve contributor tools for documentation workflow; prioritize API endpoints used by documentation sites - **CLI:** Expand command coverage documentation; improve UX docs for plugin scaffolding; create plugin documentation scaffolds; implement smoke tests for documentation examples - **Hosting:** Develop cross-host documentation checklist for recommended configurations; establish documentation defaults for common setups; collect telemetry on which docs are accessed most by host customers - **Tide:** Make scoring criteria transparent through documentation; establish false-positive review loop that feeds back to docs; create plugin outreach program about documentation quality - **Openverse:** Document ingestion pipeline for contributors; clarify moderation policy in public documentation; create education tie-ins showing proper attribution - **Themes:** Improve review throughput documentation for theme authors; document linting requirements clearly; establish mentoring program; publish test matrix documentation - **Plugins:** Similar to themes - review throughput docs; establish security liaison documentation; implement provenance check documentation for plugin developers #### The WPOCC - **Programs:** Establish fellowship track for documentation specialists; create microgrant program for ecosystem documentation improvements; develop maintainer stipend structure for critical documentation projects - **Projects:** Host governance clinics focused on documentation team structures; organize documentation sprints at major events; form release teams that include documentation leads - **Funding experiments:** Launch matched grant program for documentation initiatives; implement milestone-based payout structure for documentation deliverables; maintain transparent ledger of documentation funding ### FAIR - **Technical independence:** Ensure documentation includes local-first principles; document metadata schemas for decentralized documentation; implement provenance tracking in documentation contributions; create signature verification process for documentation updates - **Policies and covenants:** Require funding transparency for documentation initiatives; establish sunset clauses for documentation projects; create anti-capture provisions in documentation governance; publish funding sources for all documentation work - **Productized governance artifacts:** Develop documentation charters template; create operator agreements for documentation hosting; publish scorecards for documentation quality assessment; establish SLAs for community documentation support ## 🧪 Hypotheses 1. **LLM-optimized documentation increases developer acquisition:** WordPress plugins that implement structured, semantically-marked documentation with explicit parameter definitions will see a 25-40% increase in new developer adoption within 6 months, as measured through first-time contributor metrics and installation growth among developer-identified sites. 2. **Auto-generated reference docs reduce maintenance burden without sacrificing quality:** Documentation teams that implement automated reference generation for APIs and hooks will maintain 90%+ accuracy while reducing documentation update time by 50-70%, as measured through documentation drift analysis and team time tracking. 3. **Cross-linking density correlates with AI citation frequency:** Documentation sites with 3+ internal links per page will appear in AI assistant citations 2-3x more frequently than sparsely-linked documentation, as measured through citation analysis of ChatGPT, Claude, and Perplexity responses. 4. **Progressive disclosure improves developer retention:** Documentation architectures that implement clear information hierarchy (guides → tutorials → references) with explicit navigation paths will show 35-50% higher developer retention at the 30-day mark compared to flat documentation structures, as measured through authenticated user analytics. 5. **Explicit data structure documentation reduces support tickets:** Plugins that document complex return object schemas using formal specifications (JSON Schema, TypeScript definitions) will see a 40-60% reduction in support tickets related to API usage, as measured through ticket categorization analysis. 6. **Developer-psychology-aware documentation accelerates time-to-first-contribution:** Documentation that removes marketing friction and enables self-service exploration will reduce time-to-first-contribution by 30-45% compared to documentation with gated content or progressive disclosure of technical information, as measured through contributor journey analysis. ## 📊 Methodology ### Study 1: LLM Optimization Impact on Developer Acquisition **Design:** Controlled cohort study with matched pairs **Duration:** 9 months (3-month implementation + 6-month measurement) **Sample:** 60 WordPress plugins (30 intervention, 30 control), matched by current user base size, category, and growth trajectory **Intervention:** Implement structured data markup, explicit parameter documentation, and semantic HTML in documentation **Data sources:** - WordPress.org plugin installation analytics - GitHub contributor data (first-time vs. returning) - Developer survey on discovery mechanism **Analysis:** Difference-in-differences analysis comparing growth rates before/after intervention, controlling for seasonality, major releases, and marketing activities **Success criteria:** Statistically significant 25%+ increase in new developer installations with p < 0.05 ### Study 2: Auto-Generation Quality vs. Maintenance Trade-offs **Design:** Time-series analysis with quality control checkpoints **Duration:** 12 months **Sample:** 8-12 plugin documentation teams representing diverse tech stacks (PHP, JavaScript, React, Vue) **Data collection:** - Baseline: Manual documentation time per release (2 months) - Intervention: Implement auto-generation tooling (1 month) - Measurement: Track automated documentation time, human review time (9 months) - Quality assessment: Monthly accuracy audits sampling 20% of auto-generated content **Metrics:** - Time saved per release cycle - Accuracy rate (% of auto-generated content requiring no corrections) - Completeness (% of codebase with current documentation) - Developer satisfaction scores **Analysis:** Paired t-tests comparing pre/post metrics, regression analysis on accuracy over time **Success criteria:** 50%+ time reduction with 90%+ accuracy maintained ### Study 3: Citation Frequency and Cross-Linking Density **Design:** Observational correlation study with causal inference techniques **Duration:** 4 months **Sample:** 100 WordPress ecosystem documentation sites with varying link density **Data collection:** - Calculate internal link density (links per page, unique pages linked) - Query 500 developer-focused prompts across ChatGPT, Claude, Perplexity - Extract and categorize citations from responses **Analysis:** - Spearman correlation between link density and citation frequency - Propensity score matching to control for confounders (site age, content volume, domain authority) - Mediation analysis testing whether search engine ranking mediates relationship **Success criteria:** Correlation coefficient r > 0.6 with p < 0.01, maintained after controlling for confounders ### Study 4: Information Architecture and Developer Retention **Design:** Randomized controlled experiment with A/B testing **Duration:** 6 months **Sample:** 2-4 large plugins willing to implement dual documentation structures **Intervention:** - Group A: Progressive disclosure architecture (guides → tutorials → references) - Group B: Flat structure (all content at same hierarchy level) **Data sources:** - Authenticated user tracking (with consent) through developer.wordpress.com - Return visit frequency and duration - Conversion to active contributor status **Analysis:** - Survival analysis for user retention curves - Cox proportional hazards model for retention predictors - Subgroup analysis by user experience level **Success criteria:** 35%+ improvement in 30-day retention, statistically significant hazard ratio < 0.7 ### Study 5: Formal Schema Documentation and Support Reduction **Design:** Interrupted time series with multiple baselines **Duration:** 12 months (6-month baseline + 6-month post-intervention) **Sample:** 4-6 plugins with established support systems, scheduled documentation improvements **Intervention:** Implement formal schema documentation (JSON Schema, TypeScript definitions, OpenAPI specs) for complex return objects **Data sources:** - Support ticket systems (tagged and categorized) - Stack Overflow questions mentioning plugin - Support forum threads **Analysis:** - Time series analysis testing for level change and slope change - Topic modeling to confirm tickets are API-usage-related - Segmented regression analysis **Success criteria:** 40%+ reduction in API-related tickets post-intervention, sustained for 3+ months ### Study 6: Self-Service Documentation and Contribution Velocity **Design:** Quasi-experimental cohort comparison **Duration:** 8 months **Sample:** 40 open source WordPress projects, 20 with self-service docs (treatment), 20 with gated/marketing-heavy docs (control) **Data collection:** - Track contributor journey from first visit to first PR - Measure: time to first contribution, contribution depth, ongoing participation - Control for project complexity, language, maturity **Analysis:** - Kaplan-Meier survival curves for time-to-first-contribution - Multivariate regression controlling for project characteristics - Qualitative interviews with subset of contributors (n=30) **Success criteria:** 30%+ reduction in median time-to-contribution, confirmed through mixed-methods triangulation ### Cross-Study Meta-Analysis After individual studies, conduct meta-analysis to: 1. Assess effect size consistency across different contexts 2. Identify moderating factors (plugin type, audience, tech stack) 3. Develop empirically-grounded documentation quality scorecard 4. Create decision framework for documentation investment prioritization ## ❓ Questions 1. **How do different AI systems weight documentation recency vs. search ranking vs. content structure?** Understanding the relative importance of these factors could guide optimization priorities. Does a well-structured older page outperform a recent but poorly structured one? At what age does documentation become effectively invisible to AI systems? 2. **What is the optimal ratio of auto-generated to human-crafted documentation for different audience segments?** Junior developers might benefit more from extensive tutorials, while senior developers prioritize comprehensive reference docs. Can we quantify the ideal balance by developer experience level? 3. **How does cross-linking density affect AI comprehension vs. user experience?** There may be a point where extensive cross-linking helps AI systems but overwhelms human readers. Where is the inflection point? Can we A/B test this? 4. **What documentation formats most effectively bridge human and AI consumption?** Are there emerging formats (structured JSON-LD, MDX with explicit typing, semantic HTML with RDFa) that serve both audiences better than traditional approaches? 5. **How should documentation strategy differ for developer-focused vs. end-user-focused WordPress products?** The talk emphasized developer psychology, but what evidence exists for different information architectures for different audiences? Can we map documentation patterns to audience personas? 6. **What is the maintenance burden increase from adding formal schema documentation?** TypeScript definitions and JSON Schema add value but require updates with code changes. Is the reduced support burden worth the increased documentation maintenance? Can we quantify this trade-off? 7. **How does documentation influence AI-generated code quality and security?** When developers use AI to generate WordPress plugin code, does the quality and security of the output correlate with the quality and completeness of documentation the AI accessed? Can we trace vulnerabilities back to documentation gaps? 8. **What role should interactive documentation (Playground, CodePen embeds) play in AI-friendly docs?** These are valuable for human learning but may not be parseable by AI systems. Should documentation prioritize text-based examples over interactive ones, or find ways to make interactive content AI-accessible? 9. **How can we measure "AI discoverability" as a concrete documentation quality metric?** We need quantifiable metrics beyond "did an AI cite this." Can we develop a documentation SEO/GEO score that predicts AI citation frequency? 10. **What are the implications of AI training on documentation for documentation licensing and attribution?** If AI systems train on open source documentation, should documentation carry specific licenses? How do we ensure attribution in AI-generated code that relies on documentation knowledge? 11. **How should documentation teams prioritize coverage given limited resources?** Not everything can be documented comprehensively. What decision framework helps teams identify which APIs, workflows, and features warrant extensive documentation vs. minimal reference coverage? 12. **What is the role of video and audio content in AI-friendly documentation?** With improving multimodal AI, should documentation strategies include video transcripts, audio explanations, or visual diagrams explicitly designed for AI parsing? What's the ROI on different media types? ## 🔮 Future Research ### Near-term Research Directions (0-12 months) **Quantifying AI Citation Patterns:** Systematic analysis of how ChatGPT, Claude, Perplexity, and other AI assistants cite WordPress ecosystem documentation. Create a corpus of 1,000+ developer queries, analyze citation frequency, and identify documentation characteristics that predict citation rates. This foundational research would inform all other optimization efforts. **Documentation Format Experiments:** Pilot studies testing different documentation formats (MDX with TypeScript types, JSON-LD annotations, semantic HTML, plain Markdown) to determine which balance human readability and AI parsability. Measure through both human usability testing and AI assistant quality assessments. **Developer Journey Mapping:** Ethnographic research following developers as they build WordPress plugins/themes using AI assistance. Understand: Where do they get stuck? When do they consult documentation vs. AI? When do AI answers fail? What documentation gaps cause the most friction? This qualitative work can inform quantitative studies. **Support Ticket Analysis:** Natural language processing analysis of WordPress.org support forums and plugin support systems to identify documentation gaps. Use topic modeling and clustering to find patterns in questions that indicate missing or inadequate documentation. Pilot remediation efforts and measure impact. ### Medium-term Research Directions (1-2 years) **Longitudinal Documentation Evolution Study:** Track 50+ plugins over 24 months as they evolve documentation strategies in response to AI trends. Measure changes in developer acquisition, retention, support burden, and code quality. This observational study would provide real-world data on strategy effectiveness without requiring controlled interventions. **Schema Documentation Standards Development:** Research and development effort to create WordPress-specific standards for documenting hooks, filters, REST APIs, and complex return objects in ways optimized for both humans and AI. This would include developing tooling, creating reference implementations, and piloting adoption across diverse projects. **Cross-Ecosystem Comparative Analysis:** Study documentation strategies across different open source ecosystems (React, Vue, Laravel, Django, Ruby on Rails) to identify transferable patterns. What do ecosystems with strong documentation cultures do that WordPress could adopt? What unique characteristics of WordPress require different approaches? **AI-Generated Code Quality Assessment:** Large-scale analysis of AI-generated WordPress code quality. Create dataset of AI-generated plugins/themes, assess code quality through automated analysis and expert review, and attempt to correlate quality with the documentation available about the APIs used. This would quantify the documentation-quality relationship. ### Long-term Research Directions (2+ years) **Documentation as Infrastructure:** Research treating documentation as critical infrastructure requiring sustainability models. Study: What organizational structures sustain high-quality documentation? What funding models work? How do successful projects govern documentation? What's the relationship between documentation quality and project health? **Multimodal Documentation Futures:** As AI systems become more multimodal (processing text, images, video, code simultaneously), research how documentation should evolve. What combination of formats best serves both human learning and AI consumption? How should video tutorials, interactive demos, and traditional text docs integrate? **Adversarial Documentation:** Research potential misuse vectors where malicious actors could manipulate AI systems through crafted documentation (documentation poisoning). Understand risks and develop defensive strategies. What verification mechanisms could help AI systems (and humans) assess documentation trustworthiness? **Documentation Accessibility and Equity:** Research how different documentation strategies affect developers from diverse backgrounds, particularly those for whom English is not a first language, those with disabilities, and those from underrepresented communities. How do AI systems potentially amplify or mitigate documentation accessibility issues? **Economic Models for Documentation Labor:** As documentation becomes increasingly critical, research sustainable economic models. How can open source projects fund documentation work? What's the ROI of documentation investment? How do we value and compensate documentation contributors equitably? ### Methodological Development Needs **Documentation Quality Metrics:** Develop validated, reliable metrics for documentation quality that predict real-world outcomes (developer success, code quality, security, support burden). Current metrics are ad hoc; standardized assessment tools would enable comparative research. **AI Citation Attribution Tools:** Build tools that can systematically query AI systems and trace citations back to source documentation. This would enable large-scale analysis of what documentation AI systems actually use vs. what we think they should use. **Documentation Simulation Environments:** Create test environments (like Playground but for documentation) where researchers can manipulate documentation characteristics and measure impact on both human and AI consumption. This would enable rapid iteration on documentation strategies. ## 💡 Implications ### Practice Implications **For Plugin Developers:** - Immediate audit of existing documentation for AI discoverability required - Investment in structured data markup and semantic HTML will likely pay dividends in developer acquisition - Balance between comprehensive coverage and maintainable documentation must be carefully considered given limited resources - Auto-generation tools for reference documentation should be evaluated and implemented where appropriate - Support ticket patterns should inform documentation priorities—if developers repeatedly ask the same questions, documentation gaps exist **For Platform Documentation Teams:** - Multi-genre documentation strategy (guides, tutorials, references) must be intentionally designed and maintained - Cross-linking between documentation types should be systematic, not ad hoc - Information architecture decisions have measurable impact on both human and AI consumption - Progressive disclosure strategies must balance discoverability with depth of information - Documentation is no longer a post-launch activity but a core product consideration from inception **For WordPress Core:** - Existing documentation needs systematic review for AI optimization - New features should ship with structured documentation from day one - Documentation quality should be part of release criteria - Investment in documentation tooling and infrastructure is strategic, not merely supportive - Community documentation contributors need support, guidance, and potentially compensation **For Developer Relations Professionals:** - Documentation is increasingly central to developer marketing and acquisition strategy - Traditional "content marketing" vs. "technical documentation" distinction is blurring - Measurement frameworks must evolve to capture documentation's impact on key funnel metrics - Partnerships with AI tool providers may become important for understanding how documentation is consumed - DevRel role must expand to include documentation strategy, not just community engagement ### Policy Implications **Licensing and Attribution:** WordPress documentation carries GPL or compatible licenses, but implications for AI training are unclear. Should documentation carry specific licenses addressing AI training? How do we ensure proper attribution when AI-generated code draws on documentation knowledge? These questions require community discussion and potential policy development. **Quality Standards and Guidelines:** WordPress.org plugin and theme directories could implement documentation quality standards. Should plugins above certain installation thresholds be required to maintain documentation meeting specific criteria? How would such standards be enforced? What support would be provided to help developers meet them? **Resource Allocation:** If documentation is critical infrastructure, it requires sustainable funding. Should WordPress.org allocate more resources to documentation tools and support? Should sponsor companies prioritize documentation contributions? How do we value documentation work in contribution recognition systems? **Accessibility Requirements:** Documentation must be accessible to diverse audiences. Should accessibility standards for documentation be formalized and enforced? What accommodations are needed for non-native English speakers, developers with disabilities, and those with varying technical backgrounds? ### Security Implications **Documentation Gaps as Vulnerabilities:** Inadequate documentation of security-sensitive APIs can lead to insecure implementations. If developers rely on AI assistants that have incomplete knowledge due to poor documentation, security vulnerabilities may proliferate. Documentation of authentication, authorization, data sanitization, and escape functions must be explicit and prominent. **Malicious Documentation:** As AI systems increasingly rely on web-scraped documentation, there's potential for adversarial attacks where malicious actors publish misleading documentation that causes AI systems to generate vulnerable code. The WordPress ecosystem needs verification mechanisms and trusted documentation sources. **Supply Chain Transparency:** Documentation of dependencies, data flows, and third-party integrations becomes critical for security assessments. Developers using AI to scaffold plugins need clear documentation about what external services are called, what data is transmitted, and what permissions are required. **Responsible Disclosure:** Security vulnerability documentation must balance transparency (so developers can fix issues) with risk management (not providing exploitation recipes). The process for updating documentation in response to security issues needs refinement, especially considering AI systems may not immediately reflect updated information. ### Education Implications **Curriculum Development:** Computer science and coding bootcamp curricula should include documentation literacy—understanding how to read documentation, how to use AI assistants effectively with documentation, and how to write documentation that serves both human and AI readers. This is becoming as fundamental as learning to read API references. **Professional Development:** Existing developers need training on AI-assisted development workflows. This includes: when to trust AI suggestions, how to verify AI-generated code against documentation, how to craft effective prompts that leverage documentation, and how to contribute back to documentation based on their learning. **Documentation as Pedagogy:** Well-structured documentation is increasingly how people learn to build on platforms. The pedagogical quality of tutorials and guides directly impacts the skill level of the developer community. Investment in documentation is investment in education infrastructure. **Certification and Credentialing:** As AI democratizes code generation, expertise may shift from writing code to designing systems, reading documentation critically, and knowing when AI suggestions are appropriate. Certification programs may need to evolve to assess these competencies rather than code-writing ability alone. ### Funding Model Implications **Documentation as Differentiator:** In a world where AI can generate basic functionality, comprehensive, high-quality documentation becomes a competitive differentiator. Commercial plugins may invest in documentation as part of their value proposition. This could drive innovation in documentation tooling and approaches. **Open Source Sustainability:** Open source projects without commercial backing struggle to maintain documentation. As documentation becomes more critical, this sustainability challenge intensifies. Funding mechanisms—grants, sponsorships, community-supported documentation teams—need development. **Consultant and Agency Opportunities:** Specialists in WordPress documentation strategy, AI optimization, and information architecture may find increasing demand. Agencies could offer documentation audits and optimization as services. This creates economic opportunities but also risks creating barriers to entry for smaller projects. **Platform Investment Requirements:** WordPress.org and Automattic may need to significantly increase investment in documentation infrastructure, tooling, and support. This includes: better documentation hosting, improved search and discovery, tools for testing AI discoverability, and support for translation and localization. **Value Attribution:** Measuring the ROI of documentation investment remains challenging. As documentation becomes more critical, developing robust attribution models—connecting documentation quality to developer acquisition, support cost reduction, and code quality improvement—becomes essential for justifying continued investment. ## 🧠 Learning Styles Assessment **Reading Level Estimate:** Using the Flesch-Kincaid Grade Level formula on the main content section: approximately **Grade 12-13** (high school senior to first-year college level). This is appropriate for the target audience of professional developers and documentation specialists, but potentially challenging for junior developers or non-native English speakers. Consider providing executive summary sections at lower reading levels (Grade 8-10) for accessibility. #### 👀 Visual learners **Present in current content:** - Minimal visual elements in transcript format - Code example mentioned (WooCommerce local setup) but not visually represented - Search result sidebar description provides some visual context **Improvements needed:** - Architecture diagram showing relationship between LLMs, search engines, and documentation - Flowchart illustrating documentation decision tree (when to auto-generate vs. hand-craft) - Before/after comparison of documentation optimized for AI vs. traditional documentation - Screenshot examples of good cross-linking patterns - Visual representation of documentation genres (guides vs. tutorials vs. references) with characteristics - Infographic summarizing key best practices - Captions or annotations on video screenshots showing specific elements discussed #### 🔊 Aural learners **Present in current content:** - Original video with audio available - Conversational tone in transcript preserves spoken quality - Natural speech patterns and pauses indicated **Improvements needed:** - 3-5 minute audio summary extracting key insights - Podcast-style discussion elaborating on main themes - Text-to-speech friendly formatting with clear pronunciation guides for acronyms (GEO, AEO, MCP) - Speaker notes or commentary track explaining context not clear from audio alone - Audio clips highlighting particularly important quotes that could be shared standalone #### 🗣️ Verbal learners **Present in current content:** - Clear definitions of SEO, GEO, AEO terminology - Analogies present ("AI systems are basically really smart search engines in a trench coat") - Examples illustrating abstract concepts (WooCommerce local setup query) - Explicit comparisons between different documentation types **Improvements needed:** - Glossary section defining all technical terms (LLM, MCP, progressive disclosure, data structures, etc.) - More extensive use of analogies comparing documentation to familiar systems - Plain-language explanations before introducing technical terminology - Story-driven examples showing developer journey from discovering plugin through becoming contributor - Comparison tables (e.g., auto-generated vs. human-crafted, SEO vs. GEO) - Callout boxes defining terms inline when first introduced #### 🧩 Kinesthetic learners **Present in current content:** - Minimal hands-on elements in current format - Q&A section suggests practical application questions - Some step-by-step implications (auto-generate references, write guides manually) **Improvements needed:** - Interactive checklist for auditing documentation AI-readiness - Step-by-step tutorial for implementing structured data markup in WordPress docs - Hands-on exercise: "Take one piece of your documentation and optimize it for AI" with before/after review - Documentation sandbox where learners can experiment with different structures and see AI parsing results - Small experiments: "Query ChatGPT about your plugin 10 times and analyze what documentation it cites" - Worksheet for planning multi-genre documentation architecture - Reproducible task: "Auto-generate API reference documentation from your codebase" #### 🧠 Logical learners **Present in current content:** - Clear cause-effect relationship: poor documentation → AI can't discover → lost developer audience - Logical progression from problem statement through solution strategies - Data point provided (WooCommerce search example showing cited sources) - Structured argumentation in main content section **Improvements needed:** - Decision tree for documentation strategy choices based on audience, resources, and goals - RACI matrix showing who's responsible for different documentation types - Timeline showing evolution of documentation practices from pre-AI to AI-optimized future - KPI dashboard specification (what to measure and why) - Error budget framework for documentation maintenance - Causal diagram showing relationships between documentation quality, AI performance, developer acquisition, and support burden - Formal logic representation of key arguments - Cost-benefit analysis framework for documentation investment decisions #### 🧑‍🤝‍🧑 Social learners **Present in current content:** - Q&A session demonstrates community interaction - References to WordCamp US and community talks indicate social learning context - Implicit invitation to discussion through open-ended questions **Improvements needed:** - Discussion prompts for documentation team meetings or community forums - Cohort study guide for groups learning documentation strategy together - Peer review rubric for evaluating documentation quality - Collaborative exercise: "Documentation sprint planning for your team" - Q&A session facilitation guide with suggested questions and discussion topics - Case studies featuring multiple teams' approaches with opportunities for comparison - Community forum integration where learners can ask questions and share experiences - Moderated discussion series on evolving documentation practices #### 🧘‍♀️ Solitary learners **Present in current content:** - Comprehensive written content enables independent study - Self-assessment implicit in questions section - Individual reflection invited through analytical framework **Improvements needed:** - Reflection prompts after each major section: "How does your current documentation compare?" - Self-check quiz with answers: "Test your understanding of AI-friendly documentation principles" - Journaling questions: "What documentation gaps exist in your project? Why have they persisted?" - Worksheet for individual documentation strategy planning - Self-paced learning path with milestones and checkpoints - Solo exercises that don't require team coordination - Private assessment tools for evaluating own documentation quality - Reading list for deeper independent study #### 🌿 Naturalistic learners **Present in current content:** - Ecosystem thinking present (WordPress community, plugin ecosystem) - Organic evolution of practices discussed - Limited direct nature analogies **Improvements needed:** - Documentation ecosystem metaphor: treating documentation as a living system that needs feeding, pruning, and care - Lifecycle thinking: birth (new feature docs), growth (expansion and cross-linking), maturity (optimization), death (deprecation and archival) - Sustainability framework: what makes documentation practices sustainable long-term? - Environmental impact consideration: does better documentation lead to more efficient code, less compute waste? - Analogies to natural systems: documentation as mycelial network connecting knowledge nodes - Green tooling links: documentation generators with minimal environmental footprint - Patterns from nature applied to information architecture (e.g., fractal structure, redundancy, interconnection) ## 📊 Accessibility Assessment #### Screen reader semantics **Present:** - Markdown structure implies heading hierarchy - Lists used for organizing information - No visual-only information in transcript content **Improvements needed:** - Explicit ARIA landmarks if converting to HTML (`<nav>`, `<main>`, `<aside>`) - Alt text for any diagrams or screenshots added to visual learning section - Language attribute on code examples (`lang="php"`, `lang="javascript"`) - Descriptive headings that make sense out of context (screen reader users often navigate by headings) - Table of contents should use proper nav element with aria-label - Video embed should include proper caption/transcript association - Ensure any interactive elements have proper roles and states #### Keyboard navigation **Present:** - Markdown/text format is inherently keyboard accessible - No interactive elements requiring mouse **Improvements needed:** - If converting to web format, ensure skip links to main content and major sections - Video player must be fully keyboard operable (play/pause, seek, volume, captions) - Any collapsible sections must be keyboard accessible - Tab order must follow logical reading order - Focus indicators must be clearly visible (meeting 3:1 contrast ratio) - No keyboard traps in any embedded components - Ensure correct tabindex use (avoid positive tabindex values) #### Contrast and readability **Present:** - Plain text has inherent high contrast - Markdown syntax provides structure without color dependency **Improvements needed:** - If adding syntax highlighting, ensure code comments meet 4.5:1 contrast - Any colored callout boxes must maintain 4.5:1 text contrast - Link text must meet contrast requirements against background - If using color to convey meaning (e.g., red for errors), also use icons or text - Large text (18pt+ or 14pt+ bold) can use 3:1 contrast minimum - Line height should be at least 1.5 times font size - Paragraph spacing at least 2 times font size - Consider recommending dark mode alternative with appropriate contrast #### Text resizing and reflow **Present:** - Markdown naturally reflows - No fixed-width containers in current format **Improvements needed:** - Ensure content reflows at 200% zoom without horizontal scrolling (WCAG 1.4.10) - No clipping of content when zoomed - Avoid pixel-based font sizes; use rem or em units - Support prefers-reduced-motion for any animations (particularly important if adding interactive diagrams) - Test with browser zoom and text-only zoom - Ensure code blocks wrap or scroll vertically rather than horizontally - Responsive breakpoints must maintain readability at all sizes #### Media and captions **Present:** - Transcript provided (excellent accessibility practice) - Video available on WordPress.tv **Improvements needed:** - Captions on original video should be checked for accuracy (auto-captions often have errors) - Provide downloadable transcript in multiple formats (TXT, PDF, DOCX) - Audio descriptions needed if video includes visual information not conveyed in audio (slides, demos, gestures) - Ensure video player doesn't autoplay (WCAG 1.4.2) - Provide audio-only option alongside video for bandwidth-constrained users - If adding supplementary video content, include comprehensive captions and transcripts - Consider providing summary audio that covers key points for aural learners #### Forms and interactions **Present:** - No forms in current content **Improvements needed:** - If adding interactive elements (checklists, assessments): - All form fields must have associated labels - Error messages must be programmatically associated with fields - Inline validation should not remove context when errors appear - Touch targets must be at least 44x44 pixels (mobile) - Provide clear instructions before form, not only in placeholder text - Success messages must be announced to screen readers (use aria-live regions) - Forgiving input patterns (accept multiple date formats, etc.) - Clear error recovery paths - Consider accessible toast/notification patterns for feedback #### Standards reference **WCAG 2.2 AA Criteria Gaps:** - **1.1.1 Non-text Content:** Need alt text for any images, diagrams, charts added - **1.2.1 Audio-only and Video-only:** Video has transcript, but would benefit from audio description if visual information is critical - **1.4.3 Contrast:** Must verify any added visual elements meet 4.5:1 contrast - **1.4.10 Reflow:** Must ensure web version reflows at 320px width - **2.1.1 Keyboard:** Must ensure all added interactive elements are keyboard accessible - **2.4.1 Bypass Blocks:** Need skip links if creating web version with repeated navigation - **2.4.6 Headings and Labels:** Some headings could be more descriptive - **3.1.2 Language of Parts:** Need lang attributes for any code examples in other languages - **3.2.3 Consistent Navigation:** Ensure consistent navigation patterns if part of larger site - **3.3.2 Labels or Instructions:** Any future interactive elements need clear instructions - **4.1.3 Status Messages:** Any dynamic content updates must be announced **Current Accessibility Strengths:** - Semantic HTML structure (implied by Markdown) - Transcript availability - No reliance on color alone - Clear language and structure - Keyboard-accessible by default in current format ## 🌍 DEIB Assessment #### Cultural breadth **Present:** - WordPress is inherently global platform, acknowledged implicitly - WooCommerce example familiar to international audience - Technical content is relatively culturally neutral **Improvements needed:** - Examples beyond US-centric context (WordCamp US, Google-centric SEO) - Acknowledge documentation challenges for non-English languages - Include case studies from plugins/themes serving diverse markets - Discussion of documentation localization strategies - Translation links for key documentation (not just English-first approach) - Cultural context for developer psychology (independence/self-direction may be culturally influenced) - Examples of AI systems beyond US-based (Baidu, European alternatives) - Community review process that includes voices from multiple regions #### Inclusive language **Present:** - Gender-neutral language used throughout ("developers" not "guys") - No unnecessarily gendered examples - Technical jargon defined in context **Improvements needed:** - Plain-language summary section at lower reading level for broader accessibility - Glossary with definitions not assuming US tech industry context - Avoid idioms that don't translate well ("game the system," "trench coat" metaphor) - Define acronyms on first use, every time (not assuming familiarity) - Consider that "everyone knows what SEO is" may not be true globally - Expand abbreviations in ways that aid screen readers and translation - Avoid cultural assumptions about education background or technical training - Provide context for references to specific events (WordCamp US attendance) #### Neurodiversity support **Present:** - Clear structure with headings - Lists used to organize information - Consistent formatting patterns **Improvements needed:** - Increase heading frequency (more H3/H4 subheadings for chunking) - Use icons alongside text labels for major sections (visual anchors) - Predictable patterns throughout (each section uses similar structure) - Content warnings if including stressful topics (job displacement, economic disruption) - Avoid sensory language that assumes neurotypical experience - Provide multiple entry points to content (executive summary, deep dive, case studies) - Use consistent terminology (don't switch between "AI assistant" and "LLM" without noting they're equivalent) - Break very long paragraphs into shorter chunks - Use white space generously - Option to collapse/expand sections for readers who need to control information density #### Representation **Present:** - Speaker identity not specified in transcript - No demographic information about examples used - Focus on technical content minimizes need for representation in examples **Improvements needed:** - When discussing developer demographics, include diverse perspectives - Examples should feature developers with various identities where relevant - Avoid defaulting to assumed "typical developer" stereotypes - Quote and cite diverse voices in documentation field - Case studies should include projects led by underrepresented groups - Imagery (if added) should show diverse developers - Alt text should note diversity appropriately when relevant to content - Avoid assumptions about economic resources (not everyone has access to paid AI tools) - Acknowledge different paths into development (bootcamps, self-taught, formal education, career changes) #### Psychological safety **Present:** - Generally respectful framing - Acknowledges economic disruption compassionately ("we're not all excited about that") - Q&A format shows openness to questions **Improvements needed:** - Content warning about AI's impact on content economics upfront - Explicitly validate concerns about AI disruption - Acknowledge that documentation professionals may feel threatened by automation discussion - Community guidelines for any discussion forums - Clear escalation path for questions that involve sensitive topics - Moderated Q&A with focus on constructive discussion - Avoid framing that suggests "obvious" knowledge (shaming those who don't know) - Acknowledge that some developers may not want to use AI tools (respect choice) - Discussion of automation should include transition support resources - Frame challenges as system/structural issues, not individual inadequacy #### DEIB Strengths - Technical focus reduces some DEIB challenges - Open source context generally inclusive - No gatekeeping language around who can create documentation #### DEIB Gaps Requiring Attention - Assumed cultural context (primarily US/English-speaking tech industry) - Economic assumptions (resources for paid tools, time for contribution) - Educational assumptions (familiarity with specific technologies) - Language accessibility (could be challenging for non-native English speakers) - Neurodiversity considerations need explicit design - Global perspectives underrepresented ## ✅ Logical Validity #### Strong reasoning **1. Causal reasoning: Documentation → AI citation → Developer adoption** - **Location:** Summary and main content sections - **Strength:** Establishes clear chain: Well-structured docs get indexed by search → AI systems cite indexed content → Developers discover and adopt platform - **Evidence:** Concrete example of WooCommerce local setup query showing cited sources - **Why strong:** Uses observable mechanism (AI search behavior) rather than speculation - **Clarification needed:** Would benefit from quantitative data on correlation between documentation quality and adoption rates **2. Deductive reasoning: LLM limitations necessitate documentation** - **Location:** "The Continued Value of Documentation" section - **Premises:** (1) LLMs have training cutoffs, (2) New features emerge constantly, (3) LLMs need current information - **Conclusion:** Therefore documentation remains essential - **Why strong:** Valid logical structure; premises are factual and conclusion follows necessarily - **Clarification needed:** Could strengthen by addressing counterargument: "But can't LLMs be continuously retrained?" **3. Analogical reasoning: Traditional SEO principles still apply to AI discovery** - **Location:** "From SEO to GEO" section - **Analogy:** Just as content needed to rank in Google to be discovered, it needs to be findable for AI systems - **Why strong:** AI systems explicitly use search algorithms, making analogy concrete rather than metaphorical - **Clarification needed:** Should acknowledge where analogy breaks down (AI can synthesize across sources differently than search result lists) **4. Inductive reasoning: Auto-generation works well for references, not tutorials** - **Location:** "Balancing Auto-Generation and Human Craft" section - **Pattern:** Observes that reference docs have characteristics (structured, formulaic, comprehensive) that suit automation while tutorials have characteristics (narrative, pedagogical, contextual) that require human craft - **Why strong:** Based on observed properties of documentation types and demonstrated capabilities of automation tools - **Clarification needed:** Would benefit from empirical data showing quality differences **5. Conditional reasoning: If developer-focused, then specific documentation approach required** - **Location:** "Developer-Specific Considerations" section - **Conditional:** IF audience is developers THEN documentation must support self-service, avoid marketing friction, enable independence - **Why strong:** Grounded in understanding of developer psychology and behavior patterns - **Clarification needed:** Should acknowledge this is generalizing and individual developers vary #### Fallacies **1. Appeal to authority (mild)** - **Location:** References to Danny Sullivan's talk: "Google's search liaison gave a comprehensive talk" - **Weakness:** While Sullivan is indeed authoritative, the argument should stand on its merits beyond his endorsement - **Fix:** Include the specific evidence or reasoning Sullivan provided, not just cite his position - **Severity:** Minor—authority is relevant in this case and used as supporting rather than sole evidence **2. Hasty generalization (potential)** - **Location:** Developer psychology section: "Developers tend to be independent, self-starting, and averse to content that feels like a sales pitch" - **Weakness:** Generalizes from subset to entire category without acknowledging variation - **Fix:** Add qualifier: "Many developers, particularly in open source communities, tend to..." and note exceptions - **Severity:** Moderate—could lead to documentation that doesn't serve all developer segments **3. False dichotomy (implied)** - **Location:** Auto-generation vs. human craft discussion - **Weakness:** Presents these as binary choice when spectrum of approaches exists (human-edited auto-generation, AI-assisted human writing, etc.) - **Fix:** Explicitly acknowledge hybrid approaches and their trade-offs - **Severity:** Minor—text doesn't strictly claim binary, but could be read that way **4. Post hoc ergo propter hoc (potential)** - **Location:** Implicit in recommendations without empirical backing - **Weakness:** Some recommendations assume causation from correlation (e.g., AI systems cite documentation → Therefore optimizing documentation will increase citations) - **Fix:** Acknowledge these are working hypotheses pending empirical validation; hence the Hypotheses section provides testable predictions - **Severity:** Moderate—should be clear about what's proven vs. plausible **5. Slippery slope (avoided but risked)** - **Location:** Discussion of economic shifts - **Potential weakness:** Could have claimed "If AI systems don't cite your docs, your entire project will fail" - **Actually handled well:** Speaker acknowledges change without catastrophizing: "economic structures of the web are shifting, and we're not all excited about that, but there is still gonna be value" - **Severity:** N/A—fallacy was avoided **6. No true Scotsman (potential in Q&A)** - **Location:** Developer psychology discussion - **Potential weakness:** Could dismiss developers who don't fit pattern as "not real developers" - **Actually handled well:** Speaker acknowledges "if your software is more end user" different rules apply - **Severity:** N/A—fallacy was avoided #### Tone of voice **Overall tone: Pragmatic, collaborative, cautiously optimistic** **Characteristics:** 1. **Conversational authority:** Speaker uses casual language ("Hey," "you know") while demonstrating expertise. Example: "So yes, the economic structures of the web are shifting, and I don't think we're all excited about that, but there is still gonna be value..." 2. **Validation of concerns:** Acknowledges disruption and uncertainty without minimizing. Example: "We're not all excited about that" validates audience's potential anxiety about AI impact. 3. **Action-oriented:** Focuses on practical responses rather than theoretical hand-wringing. Example: "So let's talk about where the value aligns" moves from problem to solution. 4. **Humble expertise:** Makes claims without overstating certainty. Example: "I think" appears frequently, acknowledging these are informed opinions not absolute truths. 5. **Community-minded:** References shared context ("Did anybody here go to WordCamp US?") and positions content as synthesis of community wisdom, not individual authority. 6. **Realistic about complexity:** Doesn't oversimplify. Example: Discussion of documentation types acknowledges different genres require different approaches. 7. **Respectful of audience knowledge:** Explains when needed but doesn't over-explain. Example: "Everyone knows what SEO is, right?" acknowledges shared baseline while still defining it. **Tone strengths:** - Accessible without being condescending - Honest about uncertainty and change - Encouraging without being pollyannaish - Practical without being prescriptive **Tone weaknesses:** - Occasional filler words ("um," "sort of") could be edited for written content while preserving conversational feel - Some assumptions about shared context that may not hold for all audiences - Could be more explicit about limitations of speaker's own knowledge/experience ## 🛡️ DARVO Analysis **Context:** This talk does not involve accusations or defensive postures typical of DARVO patterns. The speaker is not responding to criticism or attempting to deflect blame. However, analyzing the rhetoric through this lens can identify any inadvertent defensive framing or attempts to minimize legitimate concerns. ### Deny **Not present in significant ways.** The speaker acknowledges rather than denies challenges: - Acknowledges economic disruption: "the economic structures of the web are shifting, and I don't think we're all excited about that" - Acknowledges uncertainty: frequent use of "I think" and conditional language - Acknowledges LLM limitations rather than overselling AI capabilities **Minor instance (not problematic):** - Potential minimization: "there is still gonna be value in putting fresh, relevant content forward on AI" could be interpreted as minimizing extent of disruption to content creators - **Analysis:** This is reassurance rather than denial—speaker is providing hopeful perspective, not denying that significant change is occurring - **Verdict:** Not DARVO; appropriate balance of acknowledging concern and providing constructive path forward ### Attack **Not present.** The speaker does not attack questioners, skeptics, or those with concerns about AI impact. The Q&A section shows respectful engagement with questions, even when they might challenge the talk's premises. **Tone analysis:** - Validates audience concerns rather than dismissing them - Responds to questions with substantive answers, not deflection - Acknowledges limitations of own recommendations: "if your software is more end user... then that might be different, you know?" **Verdict:** No attack rhetoric present. ### Reverse Victim/Offender **Not present.** The speaker does not position themselves or documentation creators as victims of unreasonable demands from AI skeptics or others. There's no attempt to reframe those concerned about AI's impact on content creation as the "real" problem. **Counter-evidence:** - Speaker aligns with audience concerns about economic disruption - Positions documentation creators as empowered to adapt, not as victims - Does not blame developers for changing consumption patterns - Does not frame AI companies as villains, but as reality to adapt to **Verdict:** No victim/offender reversal present. ### Emotional Cues and Rhetoric **Emotional strategies used (appropriately):** 1. **Solidarity:** "We're not all excited about that" uses inclusive "we" to show speaker shares audience concerns 2. **Reassurance:** "Don't feel bad about it" directly addresses potential anxiety about documentation value 3. **Empowerment:** Action-oriented language ("let's talk about," "so what can we do") frames audience as agents, not victims 4. **Validation:** Acknowledges that concerns are reasonable before providing solutions 5. **Honest uncertainty:** Frequent hedging ("I think," "probably," "kind of") shows intellectual humility rather than false confidence **Rhetoric analysis:** - **Ethos:** Builds credibility through community references (WordCamp US, WooCommerce experience), humility, and practical knowledge - **Pathos:** Acknowledges emotional reality of change while providing hopeful path forward; doesn't manipulate fear or anxiety - **Logos:** Grounds arguments in examples, logical reasoning, and observable patterns ### Related Fallacies (from Logical Validity section) **No toxic patterns linking to DARVO:** - The mild appeal to authority (Danny Sullivan) is not used defensively - The potential for hasty generalization about developers is not used to dismiss concerns or attack critics - The speaker explicitly invites questions and engages respectfully with challenges ### Overall DARVO Assessment **Finding: No DARVO pattern present.** This talk exemplifies healthy discourse about challenging change: - Acknowledges disruption honestly - Validates concerns - Provides constructive adaptation strategies - Invites dialogue and questions - Shows intellectual humility - Does not position speaker or any group as victim - Does not attack skeptics or those with concerns - Does not minimize real challenges while still offering hopeful perspectives **Why this matters:** DARVO analysis is typically relevant when examining defensive rhetoric in conflict situations. Its absence here indicates the speaker is engaging constructively with a challenging topic rather than defensively protecting a position or deflecting legitimate criticism. This is the appropriate stance for an educational session exploring evolving best practices. ## 🎯 Conclusion Developer documentation faces a fundamental inflection point. The rise of AI-assisted development doesn't obsolete documentation—it transforms it from optional developer experience enhancement to critical infrastructure for platform discoverability and adoption. As AI systems increasingly mediate between platforms and developers, documentation becomes the primary mechanism by which your APIs, hooks, and patterns enter the knowledge ecosystem. The strategy forward is clear: maintain freshness, embrace structure, balance automation with human craft, and design for both human and AI consumption. Auto-generate precise reference documentation that explicitly defines parameters, return types, and data structures—this is where AI systems excel at parsing and where developers need unambiguous truth. Preserve human authorship for guides and tutorials where pedagogical design, narrative flow, and contextual understanding create genuine learning experiences. Traditional SEO principles remain relevant because modern AI systems are fundamentally hybrid—they blend pre-trained knowledge with real-time search of the open web. Your documentation must be discoverable by search algorithms to be accessible to AI assistants. The emerging terminology (GEO, AEO, LLM-EO) describes the same foundational challenge: making content findable and parseable. Documentation architecture matters as much as content. Extensive cross-linking between guides, tutorials, and references helps both humans navigate and AI systems understand relationships. Progressive disclosure supports developers from first encounter through deep expertise. Information hierarchy must be intentional, not accidental. For developer audiences specifically, respect their psychology. They're independent, self-directed problem-solvers who will abandon platforms that interpose marketing friction between them and technical information. Everything must be available for self-service exploration. Documentation that feels like a sales funnel will drive developers away faster than missing documentation ever could. **Practical next steps:** 1. **Audit existing documentation** for AI discoverability: Is it structured? Fresh? Cross-linked? Semantically marked up? 2. **Implement auto-generation** for API references and hook documentation. This reduces maintenance burden while providing the explicit structure AI systems need. 3. **Invest in human-crafted guides** that explain the "why" and "when," not just the "what" and "how." This is where you build understanding that transcends function signatures. 4. **Measure and iterate.** Track which documentation AI systems cite. Monitor where developers get stuck. Let data guide priorities. 5. **Join the community conversation.** This challenge faces the entire ecosystem. Share what works, learn from others, contribute to standards development. The economic structures of the web are shifting, and that's unsettling. But in every period of disruption, those who adapt thoughtfully and quickly gain advantage. Documentation is no longer a post-launch afterthought—it's the foundation of discoverability in an AI-mediated development world. Invest accordingly. ## 🧱 Refactor Appendix ### 📚 Literature Split Pad ### LLMs require fresh documentation beyond training cutoffs > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "You know, limited to a certain amount of data, and we're always gonna have new information. We're always gonna have new data, we're always gonna have new ways to do things, new features, all that sort of stuff." LLMs have inherent cutoff dates in their training data, meaning they lack knowledge of recent features, APIs, and best practices. For current information to reach developers building on platforms, it must exist in discoverable, structured formats accessible through search. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#11:00) #xref #articleseed ID:rw_wptvai_001 ### AI systems blend search algorithms with pre-trained knowledge > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "They're still using search algorithms to find more recent relevant content and then blending that into a LLMs note." Modern AI assistants don't rely solely on training data—they actively search the web for current information and synthesize it with pre-trained knowledge. This hybrid approach means traditional SEO principles remain relevant for AI discoverability. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#12:31) #xref ID:rw_wptvai_002 ### Human-valuable content serves AI systems well > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "If content is useful to humans, it will be useful to AI." Per Danny Sullivan's guidance and community consensus, the optimal strategy is creating genuinely helpful content for humans rather than attempting to game AI systems. Quality and utility for human readers translate directly to value for AI consumption. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#13:28) #share ID:rw_wptvai_003 ### Reference docs suit automation while tutorials require human craft > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11-10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "Reference guides are generally pretty easy to auto generate... but that middle step, the guides and tutorials, that's where the kind of human element and the intentionality behind it kind of come in." Documentation ecosystems should embrace both automation and human authorship strategically. API references, hooks, and function signatures can be auto-generated efficiently, providing precise structure. Guides and tutorials require pedagogical design and contextual understanding that only human authors provide effectively. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#44:23) #articleseed ID:rw_wptvai_004 ### Explicit parameter documentation improves AI performance > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "The more concrete we can say about input and output, the better AI is gonna do." Tools like Model Context Protocol demonstrate that explicit, structured documentation of inputs and outputs significantly improves AI system performance. Being very clear about parameters, return values, and data structures helps both human developers and AI assistants understand APIs correctly. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#45:10) #xref ID:rw_wptvai_005 ### Developers resist marketing friction in documentation > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "Developers in particular have that marketing aversion. They're averse to anything that feels like a sales tactic." When targeting developers specifically, documentation must support self-service exploration without marketing friction. Developers are independent problem-solvers who quickly abandon platforms that interpose barriers between them and technical information. Everything must be available for self-directed learning. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#42:24) #articleseed ID:rw_wptvai_006 --- ### 🔖 Atomic Split Pad (Zettel Candidates) #### LLM training cutoffs necessitate discoverable documentation - LLMs lack knowledge of features and APIs released after their training data cutoff dates - Fresh documentation must exist in formats discoverable through search mechanisms - Links: [[AI Systems]] [[Documentation Strategy]] [[Information Architecture]] #### AI-mediated discovery makes SEO principles still relevant - AI assistants use search algorithms to find current content, then synthesize with pre-trained knowledge - Traditional SEO optimization helps documentation appear in AI-powered searches - Links: [[Search Engine Optimization]] [[AI Discovery]] [[Generative Engine Optimization]] #### Auto-generation suits structured reference docs better than narrative content - Reference documentation has formulaic structure and completeness requirements that suit automation - Tutorials and guides require pedagogical design and contextual storytelling that humans provide better - Links: [[Documentation Genres]] [[Automation]] [[Technical Writing]] #### Explicit type definitions improve both human and AI comprehension - Formally specifying parameters, return types, and data structures reduces ambiguity - Tools like MCP demonstrate AI performance improvements with explicit specifications - Links: [[Type Systems]] [[API Documentation]] [[Developer Experience]] #### Developer psychology requires friction-free documentation access - Developers value independence and self-service exploration - Marketing tactics and gated content drive developers away from platforms - Links: [[Developer Relations]] [[User Psychology]] [[Community Building]] #### Cross-linking density affects discoverability and comprehension - Extensive links between documentation types help humans navigate and AI systems understand relationships - Each documentation piece should acknowledge and connect to broader ecosystem - Links: [[Information Architecture]] [[Knowledge Graphs]] [[Navigation Patterns]] --- ### ✏️ Fleeting Queue (Extract by Selection) - Audit my plugin documentation for AI discoverability — measure search citation frequency — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Research auto-generation tools for PHP hook documentation — compare output quality — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Watch Danny Sullivan WordCamp US talk on SEO evolution — extract key principles — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Test ChatGPT/Claude citation patterns for WooCommerce docs — document what gets cited — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Design cross-linking strategy for documentation site — map all connection points — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Implement JSON Schema for complex return objects — improve AI and developer understanding — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Remove marketing gates from technical documentation — A/B test developer retention — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Create documentation quality scorecard — track freshness, structure, discoverability — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox --- <!-- deep-read:sections end --> [[3. Resources/Readwise/Full Document Contents/Articles/Developer Documentation in the Age of AI|Full Document Contents]] ## Document Notes --- tags: #WordPress #Documentation #AI #Developer Relations #LLM #SEO author: [MISSING] source: WordPress.tv reference: [https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/] date created: 2025-11-10 15:30 --- # 🏷️ Title: Developer Documentation in the Age of AI ## 🧭 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 - [WordPress.tv Video](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) - [VideoPress Direct Link](https://videopress.com/v/CQBhHXzU) ## 📝 Summary This WordPress.tv session explores how developer documentation must evolve in response to AI-powered coding workflows. As generative AI tools become standard in software development, the speaker argues that documentation remains critical but must be optimized for discoverability by LLMs, not just human readers. **What happened:** A WordPress community talk examining documentation strategy in the AI era, covering the evolution from SEO to "GEO" (Generative Engine Optimization), best practices for AI-friendly documentation, and the balance between comprehensive reference materials and human-crafted tutorials. **Why it matters:** With developers increasingly relying on AI assistants for code generation, platforms and plugins that fail to optimize their documentation for LLM consumption risk becoming invisible to the next generation of builders. This represents a fundamental shift in developer marketing and education strategy. **Key stakeholders:** Plugin developers, platform documentation teams, DevRel professionals, open source maintainers, WordPress core documentation contributors, and anyone responsible for developer-facing content. **Risks and tradeoffs:** Over-optimizing for AI could make documentation less useful for humans. Auto-generated reference docs may lack the context and storytelling that helps developers understand the "why" behind APIs. There's tension between comprehensive coverage and maintainability. **Bottom line:** Documentation still matters in the AI age, but the strategy must shift. Maintain fresh, structured content that search algorithms can index. Combine auto-generated API references with thoughtfully crafted guides and tutorials. Be explicit about data structures, parameters, and return values. Cross-link extensively. And remember that LLMs blend existing search with their training data, so SEO principles still apply. ## 📖 Main Content The landscape of developer education is undergoing a fundamental transformation. Every day, more code is written with the assistance of generative AI tools, from chatbots like ChatGPT and Claude to AI-infused IDEs like Cursor and GitHub Copilot. Developers increasingly rely on these tools to build functionality on existing platforms like WordPress, but this shift raises critical questions about documentation strategy. ### The Continued Value of Documentation Despite AI's capabilities, documentation remains essential because LLMs have inherent limitations. They're trained on data with cutoff dates, meaning they lack knowledge of recent features, APIs, and best practices. New information, new data, and new ways of doing things emerge constantly in the software ecosystem. For this content to reach users building on your platform, it must exist in discoverable, structured formats that both search engines and AI systems can process. The economic structures of the web are shifting, and while this evolution may be concerning to content creators, there remains significant value in publishing fresh, relevant content that AI systems can access and synthesize. The key is understanding how AI tools actually discover and use documentation. ### From SEO to GEO: The Evolution of Discovery Traditional search engine optimization (SEO) focused on helping content rank well in Google and other search engines. Now, new terms are emerging: AEO (Answer Engine Optimization), GEO (Generative Engine Optimization), and LLM-EO (Large Language Model Engine Optimization). While these acronyms sound different and have subtle distinctions, they fundamentally address the same core challenge: making content discoverable. At the end of the day, anything you create needs to be discoverable, and search remains the primary mechanism for discovery. Modern AI systems like ChatGPT and Claude don't just rely on their training data—they actively use search algorithms to find recent, relevant content and blend it into their responses. When a developer asks an LLM "How do I set up my local WooCommerce environment?", the system searches the open web, finds relevant documentation, and synthesizes it into a response with citations. This hybrid approach—combining pre-trained knowledge with real-time search—means that traditional SEO principles still matter. Your documentation needs to be findable by search algorithms for it to be useful to AI systems. ### Best Practices for AI-Friendly Documentation The speaker highlighted several key insights from the community: **Danny Sullivan's WordCamp US Talk:** Google's search liaison gave a comprehensive talk at WordCamp US about how SEO is both changing and staying the same. His core message: focus on creating useful content for humans first. If it's valuable to humans, it will be valuable to AI systems. This aligns with Google's long-standing guidance to avoid gaming the system and instead create genuinely helpful resources. **Structured Information Architecture:** While full transcripts and detailed code examples have their place, documentation should be structured for scannability and precision. Be very explicit about parameters, return values, and data structures. Tools like MCP (Model Context Protocol) demonstrate that the more concrete you can be about inputs and outputs, the better AI systems perform. **Types of Documentation:** Effective documentation ecosystems include multiple genres: - **Guides:** Higher-level content that explains philosophy, architecture, and project-level concepts - **Tutorials:** Step-by-step instructions for specific tasks, getting users from point A to point B - **Reference Documentation:** Comprehensive coverage of APIs, hooks, filters, functions—the "what" without extensive "why" ### Balancing Auto-Generation and Human Craft Reference documentation—API docs, function signatures, parameter lists—can often be auto-generated from code comments and type definitions. Tools exist for most programming languages to extract this information systematically. This is valuable and should not be skipped, as it provides the precise, structured data that LLMs need. However, the middle layer—guides and tutorials—is where human intentionality and storytelling become critical. This is where you explain not just what a function does, but when to use it, why it exists, and how it fits into broader patterns. Auto-generating tutorials rarely produces quality results because they lack the pedagogical structure and contextual understanding that makes learning effective. ### Developer-Specific Considerations When your target audience is developers specifically, there are unique considerations: **Developer Psychology:** Developers tend to be independent, self-starting, and averse to content that feels like a sales pitch. They want to dive in, experiment, and figure things out themselves. Documentation must support this learning style by providing clear, complete information without forcing them through marketing funnels. **Marketing Aversion:** Developers will quickly abandon platforms that put barriers between them and the technical information they need. Everything must be available for self-service exploration. This is especially important in the early adoption phase when developers are evaluating whether to invest time in your platform. **Progressive Disclosure:** While developers want depth available, they also benefit from progressive disclosure—starting with high-level concepts and allowing them to drill down into specifics as needed. The documentation architecture should support both quick reference and deep exploration. ### Cross-Linking and Information Architecture One of the most important but often overlooked practices is extensive cross-linking between different types of documentation. Reference docs should link to relevant tutorials. Guides should point to API references. Each piece should acknowledge and connect to the broader ecosystem of information. This cross-linking serves multiple purposes: 1. Helps human readers navigate efficiently 2. Helps search engines understand relationships between content 3. Provides context for AI systems synthesizing information from multiple sources ### Questions and Community Discussion The Q&A portion revealed ongoing tensions in documentation strategy: **Code Examples:** There's debate about how much code to include. Too much code can make documentation overwhelming and harder to maintain. But developers (and AI systems) benefit from seeing actual implementation examples, especially for complex return objects or data structures. The solution may be providing clear type definitions and schema documentation alongside selective examples. **Data Structure Documentation:** When functions return complex objects (like those from Advanced Custom Fields), it's important to document the structure explicitly. Some developers report that adding these structures as comments in their code helps AI assistants understand their intentions. This suggests documentation should include explicit schema definitions, perhaps using JSON Schema, TypeScript types, or similar formal specifications. **Maintenance Burden:** Documentation is only valuable if it stays current. Auto-generation helps with reference docs, but guides require ongoing human attention. Teams must balance comprehensiveness with maintainability, potentially prioritizing coverage of the most-used features and workflows. ## 🗒️ Notes #### ⏱️ [00:11:00](https://videopress.com/v/CQBhHXzU?at=660) Introduction - Limitations of LLMs - LLMs are limited to training data with cutoff dates - New information, features, and best practices emerge constantly - Fresh content must be discoverable to reach developers building on platforms - Economic structures of the web are shifting - Value remains in publishing relevant content for AI access #### ⏱️ [00:11:28](https://videopress.com/v/CQBhHXzU?at=688) Documentation Objectives in AI Era - AI is important but LLMs won't know everything - Documentation remains critical despite AI capabilities - Need to identify where value aligns between traditional and AI-driven approaches - Question: What are we doing now vs. what will people do next? #### ⏱️ [00:11:56](https://videopress.com/v/CQBhHXzU?at=716) From SEO to GEO - Evolution of Discovery - SEO (Search Engine Optimization) is familiar concept - New terms emerging: AEO, GEO, LLM-EO - Terms sound different but address same core challenge - Everything created needs to be discoverable - Search remains the primary discovery mechanism - LLMs use search algorithms to find recent relevant content - Example: Searching "How do I set up my local WooCommerce environment?" - LLM provides tutorial but shows websites it searched in sidebar - WooCommerce developer blog appeared in sources - Combination of LLM capabilities + open web search remains important #### ⏱️ [00:13:20](https://videopress.com/v/CQBhHXzU?at=800) Danny Sullivan's WordCamp US Talk - Attendee question: Did anyone attend WordCamp US? - Recommendation to watch Danny Sullivan's talk - Danny Sullivan works at Google - Talk covers how SEO is changing and not changing - Addresses doing things differently vs. same approaches - Important context for documentation strategy #### ⏱️ [00:13:28](https://videopress.com/v/CQBhHXzU?at=808) Core Insight - Human Value First - The most important insight from multiple sources - If content is useful to humans, it will be useful to AI - Avoid attempting to game the system - Focus on creating genuinely helpful resources - This principle applies across documentation types #### ⏱️ [00:14:36](https://videopress.com/v/CQBhHXzU?at=876) Practical Example - Local Setup Documentation - WooCommerce has local setup documentation - When asked about creating documentation pages - Can use AI to generate initial draft - Important: AI should not be generating content directly for publication - AI assists in drafting, humans ensure quality and accuracy #### ⏱️ [00:15:55](https://videopress.com/v/CQBhHXzU?at=955) Documentation Structure and Scannability - Discussion about full transcripts vs. structured content - Transcripts have value but can be overwhelming - Documentation should be structured for scannability - Users need to find specific information quickly - Balance between comprehensiveness and usability #### ⏱️ [00:21:15](https://videopress.com/v/CQBhHXzU?at=1275) Best Practices Summary - Focus on fresh, relevant content - Structure for both human and AI consumption - Be explicit about parameters and return values - Cross-link between documentation types - Maintain different genres: guides, tutorials, references - Auto-generate where possible, craft tutorials with intention #### ⏱️ [00:42:24](https://videopress.com/v/CQBhHXzU?at=2544) Developer Psychology and Marketing Aversion - Developers are independent and self-starting - Want to get through documentation on their own - Averse to anything that feels like sales tactics - If target market is developers, must be very clear - Everything must be available for self-service - Let developers be self-starting enough to invest in platform - Developers will jump off quickly if they sense marketing manipulation - Different considerations for end-user focused software #### ⏱️ [00:42:58](https://videopress.com/v/CQBhHXzU?at=2578) Q&A - Code Examples and Data Structures - Question about putting too much code in documentation - Specific concern: functions returning complex objects (e.g., ACF) - Challenge: How to make AI aware of data structures - Developer's approach: putting data structures in code comments - Makes AI assistants smarter about intentions - Question: Where to put this information in documentation? #### ⏱️ [00:43:49](https://videopress.com/v/CQBhHXzU?at=2629) Documentation Genres and Types - Different types of documentation serve different purposes - **Guides:** Higher level, philosophy, project-level concepts - **Tutorials:** Step-by-step, one specific task from A to B - Not comprehensive coverage of feature - Focused on accomplishing specific goal - **References:** Exhaustive coverage of APIs, hooks, filters - Example: WooCommerce has developer docs, REST API reference, and codex - Each type serves different use cases #### ⏱️ [00:44:23](https://videopress.com/v/CQBhHXzU?at=2663) Cross-Linking and Reference Generation - Having reference guides and cross-linking is important - Reference documentation is generally easy to auto-generate - Makes sense to find good tools for your language/platform - Should not skip the reference guide component - Middle step (guides/tutorials) requires human element - Intentionality behind guides and tutorials matters - Mix of auto-generated references and human-crafted guides #### ⏱️ [00:45:10](https://videopress.com/v/CQBhHXzU?at=2710) Explicit Parameters and MCP - Being very explicit about input/output parameters is extremely important - Example: Tools like MCP (Model Context Protocol) - The more concrete you can be about input and output, the better AI performs - Continue keeping parameters and return values updated - This helps both humans and AI systems understand your APIs ## 📚 References - [WordPress.tv - Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) - [VideoPress Direct Link](https://videopress.com/v/CQBhHXzU) - [Danny Sullivan's WordCamp US Talk](https://wordpress.tv) (specific link not provided in transcript) - [WooCommerce Developer Blog](https://developer.woocommerce.com/blog/) - [WooCommerce Developer Documentation](https://developer.woocommerce.com/) - [WooCommerce REST API Reference](https://woocommerce.github.io/woocommerce-rest-api-docs/) - [Google Search Central](https://developers.google.com/search) - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Advanced Custom Fields (ACF) - mentioned in Q&A - ChatGPT, Claude - example AI assistants mentioned - Cursor, GitHub Copilot - AI-infused IDEs mentioned ## 🗣️ Paraphrase The fundamental shift toward AI-assisted development doesn't diminish the importance of documentation—it transforms how documentation must be created and structured. While Large Language Models have impressive capabilities, they're constrained by training cutoffs and need access to current information through search mechanisms. This means traditional SEO principles remain relevant even as new concepts like Generative Engine Optimization emerge. The core insight, echoed across community experts like Google's Danny Sullivan, is straightforward: create documentation that genuinely helps humans, and it will naturally serve AI systems well. This isn't about gaming algorithms but about providing clear, structured, discoverable information. The hybrid approach modern AI systems take—blending pre-trained knowledge with real-time search of the open web—means your documentation must be findable to be useful. Documentation strategy should embrace a multi-genre approach. Auto-generate precise reference materials that define APIs, parameters, and return values with technical accuracy—this is where automation excels and AI systems benefit most from explicit structure. But preserve human authorship for guides and tutorials, where storytelling, context, and pedagogical design create understanding that transcends mere function signatures. For developer audiences specifically, documentation must respect their self-directed learning style. Developers are independent problem-solvers who quickly abandon platforms that interpose marketing friction between them and technical information. Everything must be available for self-service exploration, with progressive disclosure allowing quick reference for experts and deeper explanation for newcomers. The information architecture matters as much as the content itself. Extensive cross-linking between different documentation types helps humans navigate, helps search engines understand relationships, and provides critical context for AI systems synthesizing from multiple sources. A tutorial should link to relevant API references; a reference should point to practical guides; everything should acknowledge the broader ecosystem. As tools like the Model Context Protocol demonstrate, being explicit about data structures, inputs, and outputs significantly improves how AI systems work with your platform. When functions return complex objects, document their shape formally—consider JSON Schema, TypeScript definitions, or equivalent specifications that both humans and machines can parse reliably. The maintenance challenge remains real. Auto-generation helps with reference docs, but guides require ongoing human attention. Teams must balance comprehensiveness with sustainability, potentially prioritizing coverage of the most-used features and workflows while maintaining freshness where it matters most. Documentation is only valuable if it stays current, and currency requires sustainable processes. ## 📰 Newsletter **📚 Your Documentation Strategy Needs an AI Upgrade (But Not the Way You Think)** Hey WordPress community! 👋 If you've been wondering whether your plugin's documentation still matters now that everyone's coding with ChatGPT and Claude, I've got news: it matters more than ever, but the playbook is changing. Fresh off WordPress.tv comes a must-watch session on developer documentation in the age of AI. Spoiler alert: The robots aren't replacing your docs—they're *using* them. And if your docs aren't discoverable, your plugin might as well be invisible to the next generation of builders. Here's the thing: LLMs don't actually know everything. Shocking, right? They've got training cutoffs, which means that killer new feature you shipped last month? Totally unknown unless it's documented and discoverable on the open web. Modern AI assistants are basically really smart search engines in a trench coat—they search the web in real-time and synthesize what they find. So yes, SEO still matters. Call it GEO, call it AEO, call it whatever acronym makes your heart happy—it's all about making content findable. **The golden rule** (courtesy of Google's Danny Sullivan at WordCamp US): If it's useful to humans, it'll be useful to AI. Don't try to game the system. Just make genuinely helpful stuff. Revolutionary, I know. 😉 **Here's what your documentation stack needs:** - **Reference docs** → Auto-generate these! Your APIs, hooks, filters—all that technical precision is perfect for automation. Be super explicit about parameters and return types. Tools like MCP are proving that the more concrete you are about inputs/outputs, the better AI performs. - **Tutorials** → Keep humans in the loop here. Step-by-step guides need that pedagogical structure and context that only human authors can provide. Take developers from A to B on one specific task. - **Guides** → Philosophy, architecture, the "why" behind your design—this is where storytelling matters. AI can't generate your platform's vision. **Pro tips from the talk:** - Cross-link everything. Your reference docs should point to tutorials. Your tutorials should link to references. Help humans navigate AND give AI the relationship context it needs. - Know your audience. If you're targeting developers specifically, remember they're independent, self-starting, and will bounce immediately if your docs feel like a sales funnel. Everything must be available for self-service exploration. - Document those data structures! When your function returns a complex object (looking at you, ACF), be explicit about the schema. Some devs are already putting these in code comments to help AI assistants—imagine how much better your docs could be with formal definitions. The economics of the web are shifting, and yeah, that's unsettling. But there's still massive value in publishing fresh, relevant, well-structured content. The combination of LLM knowledge + real-time web search isn't going anywhere. So audit your docs. Are they discoverable? Structured? Up to date? Do they balance auto-generated precision with human-crafted guidance? Your future developers (and their AI assistants) will thank you. **Resources to check out:** - [Watch the full WordCamp talk](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) - [WooCommerce Developer Blog](https://developer.woocommerce.com/blog/) (mentioned as an example of discoverable docs) - [Danny Sullivan's SEO talk from WordCamp US](https://wordpress.tv) (seriously, watch this) Happy documenting! 📝✨ ## ✅ Action Items #### DevRel - **Developer advocacy:** Create presentation deck on AI-friendly documentation patterns for WordCamp circuit; measure adoption through follow-up surveys - **Education:** Host monthly office hours on documentation strategy for plugin developers; create 4-week workshop series on balancing auto-generated vs. human-crafted content - **Developer experience:** Audit WooCommerce documentation for AI discoverability; implement structured data markup on all API reference pages; measure engagement through search analytics - **Developer marketing:** Launch content campaign highlighting documentation as competitive advantage; create comparison matrix showing documentation approaches across ecosystem - **Community management:** Establish documentation review process in plugin repository guidelines; moderate #docs channel with focus on AI-readiness discussions - **Internal alignment:** Coordinate with SEO team on GEO/AEO strategies; establish feedback loop between support tickets and documentation gaps; set SLAs for documentation updates tied to release cycles - **External collaboration:** Partner with AI tool providers (Claude, ChatGPT teams) to understand how they index WordPress docs; share learnings with ecosystem - **Cross-project:** Present documentation findings at WordPress Contributor Day; collaborate with Training team on documentation best practices course #### OSPO - **Policy & Governance:** Develop documentation standards policy for projects receiving OSPO support; establish contribution guidelines for AI-generated content in docs - **License Compliance:** Review auto-generation tools for license compatibility; ensure documentation generation pipeline respects upstream licenses - **Security Management:** Establish vulnerability disclosure process that includes documentation updates; ensure security advisories reference specific doc sections - **Software Inventory:** Include documentation status in SBOM; track which components have AI-optimized docs vs. legacy formats - **Developer Support:** Create consultation hours specifically for documentation strategy; develop tooling recommendations by language/framework - **Community Engagement:** Fund documentation sprints at WordCamps; provide stipends for documentation maintainers in key ecosystem projects - **Strategic Alignment:** Include documentation quality KPIs in quarterly OKRs; executive reporting on documentation as strategic initiative; track "documentation debt" as technical debt metric #### Community - **Maintainers:** Conduct documentation roadmap clinics at Contributor Days; create governance templates for documentation team structures; establish release hygiene checklists that include docs updates - **Contributors:** Design "first documentation issue" rotation program; pair new contributors with experienced docs writers; create getting-started guide specifically for documentation contributions - **Sponsors:** Develop transparent budget proposals for documentation initiatives; define clear milestones for funded documentation projects; create impact reports showing discoverability improvements - **Ecosystem:** Organize cross-project documentation incident drills (what if major API changes?); coordinate disclosure process that includes docs updates across dependent projects #### WordPress - **Core:** Prioritize documentation for new features in 6.9 release; establish triage process for docs issues linking to support forum patterns; set performance budgets for docs site loading; define release criteria that include documentation completeness - **Core Performance:** Create profiling documentation showing before/after optimization examples; build metrics dashboard for docs site performance; establish performance bounty program for docs improvements - **Core AI:** Develop responsible AI guardrails for using AI in documentation generation; create evaluation sets for AI-generated docs quality; pilot project using LLMs to identify documentation gaps - **Core Program Team:** Establish coordination rituals between component teams and docs team; map cross-team dependencies for major initiatives; conduct retrospectives on documentation handoffs - **Mobile:** Document mobile-specific considerations for plugin developers; review app documentation for AI discoverability; improve offline documentation UX - **Playground:** Create browser-based documentation labs where developers can test examples; build reproducible bug report templates that include documentation context; develop education modules using Playground for interactive tutorials - **Community:** Create meetup presentation kits on documentation best practices; develop WordCamp documentation track playbook; establish speaker mentorship program for documentation topics - **Training:** Develop lesson plans on creating AI-friendly documentation; create learning path from basic docs writing to comprehensive documentation architecture; pilot certification program for documentation specialists - **Marketing:** Launch campaign highlighting WordPress documentation excellence; develop narrative around "documentation as developer experience"; create social editorial calendar featuring documentation wins - **Support:** Set response SLAs for documentation-related questions; identify knowledge base gaps through ticket analysis; create escalation path from support to docs team - **Design:** Conduct UX audit of developer documentation sites; develop design tokens for documentation systems; maintain research backlog on developer information-seeking behavior - **Documentation:** Close DevHub/HelpHub gaps identified in accessibility audit; implement examples-first pattern in new content; update style guide with AI-optimization guidelines - **Photos:** Maintain documentation images for common WordPress UI patterns; establish moderation guidelines for screenshot submissions; improve taxonomy for searchable image metadata - **TV:** Create submission guide specifically for documentation-related talks; improve caption quality through AI-assisted review; implement content indexing for video documentation - **Polyglots:** Coordinate translation sprints for high-impact documentation; align glossary terms across locales; track locale coverage of critical documentation - **Accessibility:** Conduct WCAG review of major documentation sites; develop documentation-specific accessibility tooling; create issues heatmap showing common accessibility problems; establish quarterly audit cadence - **Meta:** Include documentation search in .org API reliability metrics; improve contributor tools for documentation workflow; prioritize API endpoints used by documentation sites - **CLI:** Expand command coverage documentation; improve UX docs for plugin scaffolding; create plugin documentation scaffolds; implement smoke tests for documentation examples - **Hosting:** Develop cross-host documentation checklist for recommended configurations; establish documentation defaults for common setups; collect telemetry on which docs are accessed most by host customers - **Tide:** Make scoring criteria transparent through documentation; establish false-positive review loop that feeds back to docs; create plugin outreach program about documentation quality - **Openverse:** Document ingestion pipeline for contributors; clarify moderation policy in public documentation; create education tie-ins showing proper attribution - **Themes:** Improve review throughput documentation for theme authors; document linting requirements clearly; establish mentoring program; publish test matrix documentation - **Plugins:** Similar to themes - review throughput docs; establish security liaison documentation; implement provenance check documentation for plugin developers #### The WPCC - **Programs:** Establish fellowship track for documentation specialists; create microgrant program for ecosystem documentation improvements; develop maintainer stipend structure for critical documentation projects - **Projects:** Host governance clinics focused on documentation team structures; organize documentation sprints at major events; form release teams that include documentation leads - **Funding experiments:** Launch matched grant program for documentation initiatives; implement milestone-based payout structure for documentation deliverables; maintain transparent ledger of documentation funding ### FAIR - **Technical independence:** Ensure documentation includes local-first principles; document metadata schemas for decentralized documentation; implement provenance tracking in documentation contributions; create signature verification process for documentation updates - **Policies and covenants:** Require funding transparency for documentation initiatives; establish sunset clauses for documentation projects; create anti-capture provisions in documentation governance; publish funding sources for all documentation work - **Productized governance artifacts:** Develop documentation charters template; create operator agreements for documentation hosting; publish scorecards for documentation quality assessment; establish SLAs for community documentation support ## 🧪 Hypotheses 1. **LLM-optimized documentation increases developer acquisition:** WordPress plugins that implement structured, semantically-marked documentation with explicit parameter definitions will see a 25-40% increase in new developer adoption within 6 months, as measured through first-time contributor metrics and installation growth among developer-identified sites. 2. **Auto-generated reference docs reduce maintenance burden without sacrificing quality:** Documentation teams that implement automated reference generation for APIs and hooks will maintain 90%+ accuracy while reducing documentation update time by 50-70%, as measured through documentation drift analysis and team time tracking. 3. **Cross-linking density correlates with AI citation frequency:** Documentation sites with 3+ internal links per page will appear in AI assistant citations 2-3x more frequently than sparsely-linked documentation, as measured through citation analysis of ChatGPT, Claude, and Perplexity responses. 4. **Progressive disclosure improves developer retention:** Documentation architectures that implement clear information hierarchy (guides → tutorials → references) with explicit navigation paths will show 35-50% higher developer retention at the 30-day mark compared to flat documentation structures, as measured through authenticated user analytics. 5. **Explicit data structure documentation reduces support tickets:** Plugins that document complex return object schemas using formal specifications (JSON Schema, TypeScript definitions) will see a 40-60% reduction in support tickets related to API usage, as measured through ticket categorization analysis. 6. **Developer-psychology-aware documentation accelerates time-to-first-contribution:** Documentation that removes marketing friction and enables self-service exploration will reduce time-to-first-contribution by 30-45% compared to documentation with gated content or progressive disclosure of technical information, as measured through contributor journey analysis. ## 📊 Methodology ### Study 1: LLM Optimization Impact on Developer Acquisition **Design:** Controlled cohort study with matched pairs **Duration:** 9 months (3-month implementation + 6-month measurement) **Sample:** 60 WordPress plugins (30 intervention, 30 control), matched by current user base size, category, and growth trajectory **Intervention:** Implement structured data markup, explicit parameter documentation, and semantic HTML in documentation **Data sources:** - WordPress.org plugin installation analytics - GitHub contributor data (first-time vs. returning) - Developer survey on discovery mechanism **Analysis:** Difference-in-differences analysis comparing growth rates before/after intervention, controlling for seasonality, major releases, and marketing activities **Success criteria:** Statistically significant 25%+ increase in new developer installations with p < 0.05 ### Study 2: Auto-Generation Quality vs. Maintenance Trade-offs **Design:** Time-series analysis with quality control checkpoints **Duration:** 12 months **Sample:** 8-12 plugin documentation teams representing diverse tech stacks (PHP, JavaScript, React, Vue) **Data collection:** - Baseline: Manual documentation time per release (2 months) - Intervention: Implement auto-generation tooling (1 month) - Measurement: Track automated documentation time, human review time (9 months) - Quality assessment: Monthly accuracy audits sampling 20% of auto-generated content **Metrics:** - Time saved per release cycle - Accuracy rate (% of auto-generated content requiring no corrections) - Completeness (% of codebase with current documentation) - Developer satisfaction scores **Analysis:** Paired t-tests comparing pre/post metrics, regression analysis on accuracy over time **Success criteria:** 50%+ time reduction with 90%+ accuracy maintained ### Study 3: Citation Frequency and Cross-Linking Density **Design:** Observational correlation study with causal inference techniques **Duration:** 4 months **Sample:** 100 WordPress ecosystem documentation sites with varying link density **Data collection:** - Calculate internal link density (links per page, unique pages linked) - Query 500 developer-focused prompts across ChatGPT, Claude, Perplexity - Extract and categorize citations from responses **Analysis:** - Spearman correlation between link density and citation frequency - Propensity score matching to control for confounders (site age, content volume, domain authority) - Mediation analysis testing whether search engine ranking mediates relationship **Success criteria:** Correlation coefficient r > 0.6 with p < 0.01, maintained after controlling for confounders ### Study 4: Information Architecture and Developer Retention **Design:** Randomized controlled experiment with A/B testing **Duration:** 6 months **Sample:** 2-4 large plugins willing to implement dual documentation structures **Intervention:** - Group A: Progressive disclosure architecture (guides → tutorials → references) - Group B: Flat structure (all content at same hierarchy level) **Data sources:** - Authenticated user tracking (with consent) through developer.wordpress.com - Return visit frequency and duration - Conversion to active contributor status **Analysis:** - Survival analysis for user retention curves - Cox proportional hazards model for retention predictors - Subgroup analysis by user experience level **Success criteria:** 35%+ improvement in 30-day retention, statistically significant hazard ratio < 0.7 ### Study 5: Formal Schema Documentation and Support Reduction **Design:** Interrupted time series with multiple baselines **Duration:** 12 months (6-month baseline + 6-month post-intervention) **Sample:** 4-6 plugins with established support systems, scheduled documentation improvements **Intervention:** Implement formal schema documentation (JSON Schema, TypeScript definitions, OpenAPI specs) for complex return objects **Data sources:** - Support ticket systems (tagged and categorized) - Stack Overflow questions mentioning plugin - Support forum threads **Analysis:** - Time series analysis testing for level change and slope change - Topic modeling to confirm tickets are API-usage-related - Segmented regression analysis **Success criteria:** 40%+ reduction in API-related tickets post-intervention, sustained for 3+ months ### Study 6: Self-Service Documentation and Contribution Velocity **Design:** Quasi-experimental cohort comparison **Duration:** 8 months **Sample:** 40 open source WordPress projects, 20 with self-service docs (treatment), 20 with gated/marketing-heavy docs (control) **Data collection:** - Track contributor journey from first visit to first PR - Measure: time to first contribution, contribution depth, ongoing participation - Control for project complexity, language, maturity **Analysis:** - Kaplan-Meier survival curves for time-to-first-contribution - Multivariate regression controlling for project characteristics - Qualitative interviews with subset of contributors (n=30) **Success criteria:** 30%+ reduction in median time-to-contribution, confirmed through mixed-methods triangulation ### Cross-Study Meta-Analysis After individual studies, conduct meta-analysis to: 1. Assess effect size consistency across different contexts 2. Identify moderating factors (plugin type, audience, tech stack) 3. Develop empirically-grounded documentation quality scorecard 4. Create decision framework for documentation investment prioritization ## ❓ Questions 1. **How do different AI systems weight documentation recency vs. search ranking vs. content structure?** Understanding the relative importance of these factors could guide optimization priorities. Does a well-structured older page outperform a recent but poorly structured one? At what age does documentation become effectively invisible to AI systems? 2. **What is the optimal ratio of auto-generated to human-crafted documentation for different audience segments?** Junior developers might benefit more from extensive tutorials, while senior developers prioritize comprehensive reference docs. Can we quantify the ideal balance by developer experience level? 3. **How does cross-linking density affect AI comprehension vs. user experience?** There may be a point where extensive cross-linking helps AI systems but overwhelms human readers. Where is the inflection point? Can we A/B test this? 4. **What documentation formats most effectively bridge human and AI consumption?** Are there emerging formats (structured JSON-LD, MDX with explicit typing, semantic HTML with RDFa) that serve both audiences better than traditional approaches? 5. **How should documentation strategy differ for developer-focused vs. end-user-focused WordPress products?** The talk emphasized developer psychology, but what evidence exists for different information architectures for different audiences? Can we map documentation patterns to audience personas? 6. **What is the maintenance burden increase from adding formal schema documentation?** TypeScript definitions and JSON Schema add value but require updates with code changes. Is the reduced support burden worth the increased documentation maintenance? Can we quantify this trade-off? 7. **How does documentation influence AI-generated code quality and security?** When developers use AI to generate WordPress plugin code, does the quality and security of the output correlate with the quality and completeness of documentation the AI accessed? Can we trace vulnerabilities back to documentation gaps? 8. **What role should interactive documentation (Playground, CodePen embeds) play in AI-friendly docs?** These are valuable for human learning but may not be parseable by AI systems. Should documentation prioritize text-based examples over interactive ones, or find ways to make interactive content AI-accessible? 9. **How can we measure "AI discoverability" as a concrete documentation quality metric?** We need quantifiable metrics beyond "did an AI cite this." Can we develop a documentation SEO/GEO score that predicts AI citation frequency? 10. **What are the implications of AI training on documentation for documentation licensing and attribution?** If AI systems train on open source documentation, should documentation carry specific licenses? How do we ensure attribution in AI-generated code that relies on documentation knowledge? 11. **How should documentation teams prioritize coverage given limited resources?** Not everything can be documented comprehensively. What decision framework helps teams identify which APIs, workflows, and features warrant extensive documentation vs. minimal reference coverage? 12. **What is the role of video and audio content in AI-friendly documentation?** With improving multimodal AI, should documentation strategies include video transcripts, audio explanations, or visual diagrams explicitly designed for AI parsing? What's the ROI on different media types? ## 🔮 Future Research ### Near-term Research Directions (0-12 months) **Quantifying AI Citation Patterns:** Systematic analysis of how ChatGPT, Claude, Perplexity, and other AI assistants cite WordPress ecosystem documentation. Create a corpus of 1,000+ developer queries, analyze citation frequency, and identify documentation characteristics that predict citation rates. This foundational research would inform all other optimization efforts. **Documentation Format Experiments:** Pilot studies testing different documentation formats (MDX with TypeScript types, JSON-LD annotations, semantic HTML, plain Markdown) to determine which balance human readability and AI parsability. Measure through both human usability testing and AI assistant quality assessments. **Developer Journey Mapping:** Ethnographic research following developers as they build WordPress plugins/themes using AI assistance. Understand: Where do they get stuck? When do they consult documentation vs. AI? When do AI answers fail? What documentation gaps cause the most friction? This qualitative work can inform quantitative studies. **Support Ticket Analysis:** Natural language processing analysis of WordPress.org support forums and plugin support systems to identify documentation gaps. Use topic modeling and clustering to find patterns in questions that indicate missing or inadequate documentation. Pilot remediation efforts and measure impact. ### Medium-term Research Directions (1-2 years) **Longitudinal Documentation Evolution Study:** Track 50+ plugins over 24 months as they evolve documentation strategies in response to AI trends. Measure changes in developer acquisition, retention, support burden, and code quality. This observational study would provide real-world data on strategy effectiveness without requiring controlled interventions. **Schema Documentation Standards Development:** Research and development effort to create WordPress-specific standards for documenting hooks, filters, REST APIs, and complex return objects in ways optimized for both humans and AI. This would include developing tooling, creating reference implementations, and piloting adoption across diverse projects. **Cross-Ecosystem Comparative Analysis:** Study documentation strategies across different open source ecosystems (React, Vue, Laravel, Django, Ruby on Rails) to identify transferable patterns. What do ecosystems with strong documentation cultures do that WordPress could adopt? What unique characteristics of WordPress require different approaches? **AI-Generated Code Quality Assessment:** Large-scale analysis of AI-generated WordPress code quality. Create dataset of AI-generated plugins/themes, assess code quality through automated analysis and expert review, and attempt to correlate quality with the documentation available about the APIs used. This would quantify the documentation-quality relationship. ### Long-term Research Directions (2+ years) **Documentation as Infrastructure:** Research treating documentation as critical infrastructure requiring sustainability models. Study: What organizational structures sustain high-quality documentation? What funding models work? How do successful projects govern documentation? What's the relationship between documentation quality and project health? **Multimodal Documentation Futures:** As AI systems become more multimodal (processing text, images, video, code simultaneously), research how documentation should evolve. What combination of formats best serves both human learning and AI consumption? How should video tutorials, interactive demos, and traditional text docs integrate? **Adversarial Documentation:** Research potential misuse vectors where malicious actors could manipulate AI systems through crafted documentation (documentation poisoning). Understand risks and develop defensive strategies. What verification mechanisms could help AI systems (and humans) assess documentation trustworthiness? **Documentation Accessibility and Equity:** Research how different documentation strategies affect developers from diverse backgrounds, particularly those for whom English is not a first language, those with disabilities, and those from underrepresented communities. How do AI systems potentially amplify or mitigate documentation accessibility issues? **Economic Models for Documentation Labor:** As documentation becomes increasingly critical, research sustainable economic models. How can open source projects fund documentation work? What's the ROI of documentation investment? How do we value and compensate documentation contributors equitably? ### Methodological Development Needs **Documentation Quality Metrics:** Develop validated, reliable metrics for documentation quality that predict real-world outcomes (developer success, code quality, security, support burden). Current metrics are ad hoc; standardized assessment tools would enable comparative research. **AI Citation Attribution Tools:** Build tools that can systematically query AI systems and trace citations back to source documentation. This would enable large-scale analysis of what documentation AI systems actually use vs. what we think they should use. **Documentation Simulation Environments:** Create test environments (like Playground but for documentation) where researchers can manipulate documentation characteristics and measure impact on both human and AI consumption. This would enable rapid iteration on documentation strategies. ## 💡 Implications ### Practice Implications **For Plugin Developers:** - Immediate audit of existing documentation for AI discoverability required - Investment in structured data markup and semantic HTML will likely pay dividends in developer acquisition - Balance between comprehensive coverage and maintainable documentation must be carefully considered given limited resources - Auto-generation tools for reference documentation should be evaluated and implemented where appropriate - Support ticket patterns should inform documentation priorities—if developers repeatedly ask the same questions, documentation gaps exist **For Platform Documentation Teams:** - Multi-genre documentation strategy (guides, tutorials, references) must be intentionally designed and maintained - Cross-linking between documentation types should be systematic, not ad hoc - Information architecture decisions have measurable impact on both human and AI consumption - Progressive disclosure strategies must balance discoverability with depth of information - Documentation is no longer a post-launch activity but a core product consideration from inception **For WordPress Core:** - Existing documentation needs systematic review for AI optimization - New features should ship with structured documentation from day one - Documentation quality should be part of release criteria - Investment in documentation tooling and infrastructure is strategic, not merely supportive - Community documentation contributors need support, guidance, and potentially compensation **For Developer Relations Professionals:** - Documentation is increasingly central to developer marketing and acquisition strategy - Traditional "content marketing" vs. "technical documentation" distinction is blurring - Measurement frameworks must evolve to capture documentation's impact on key funnel metrics - Partnerships with AI tool providers may become important for understanding how documentation is consumed - DevRel role must expand to include documentation strategy, not just community engagement ### Policy Implications **Licensing and Attribution:** WordPress documentation carries GPL or compatible licenses, but implications for AI training are unclear. Should documentation carry specific licenses addressing AI training? How do we ensure proper attribution when AI-generated code draws on documentation knowledge? These questions require community discussion and potential policy development. **Quality Standards and Guidelines:** WordPress.org plugin and theme directories could implement documentation quality standards. Should plugins above certain installation thresholds be required to maintain documentation meeting specific criteria? How would such standards be enforced? What support would be provided to help developers meet them? **Resource Allocation:** If documentation is critical infrastructure, it requires sustainable funding. Should WordPress.org allocate more resources to documentation tools and support? Should sponsor companies prioritize documentation contributions? How do we value documentation work in contribution recognition systems? **Accessibility Requirements:** Documentation must be accessible to diverse audiences. Should accessibility standards for documentation be formalized and enforced? What accommodations are needed for non-native English speakers, developers with disabilities, and those with varying technical backgrounds? ### Security Implications **Documentation Gaps as Vulnerabilities:** Inadequate documentation of security-sensitive APIs can lead to insecure implementations. If developers rely on AI assistants that have incomplete knowledge due to poor documentation, security vulnerabilities may proliferate. Documentation of authentication, authorization, data sanitization, and escape functions must be explicit and prominent. **Malicious Documentation:** As AI systems increasingly rely on web-scraped documentation, there's potential for adversarial attacks where malicious actors publish misleading documentation that causes AI systems to generate vulnerable code. The WordPress ecosystem needs verification mechanisms and trusted documentation sources. **Supply Chain Transparency:** Documentation of dependencies, data flows, and third-party integrations becomes critical for security assessments. Developers using AI to scaffold plugins need clear documentation about what external services are called, what data is transmitted, and what permissions are required. **Responsible Disclosure:** Security vulnerability documentation must balance transparency (so developers can fix issues) with risk management (not providing exploitation recipes). The process for updating documentation in response to security issues needs refinement, especially considering AI systems may not immediately reflect updated information. ### Education Implications **Curriculum Development:** Computer science and coding bootcamp curricula should include documentation literacy—understanding how to read documentation, how to use AI assistants effectively with documentation, and how to write documentation that serves both human and AI readers. This is becoming as fundamental as learning to read API references. **Professional Development:** Existing developers need training on AI-assisted development workflows. This includes: when to trust AI suggestions, how to verify AI-generated code against documentation, how to craft effective prompts that leverage documentation, and how to contribute back to documentation based on their learning. **Documentation as Pedagogy:** Well-structured documentation is increasingly how people learn to build on platforms. The pedagogical quality of tutorials and guides directly impacts the skill level of the developer community. Investment in documentation is investment in education infrastructure. **Certification and Credentialing:** As AI democratizes code generation, expertise may shift from writing code to designing systems, reading documentation critically, and knowing when AI suggestions are appropriate. Certification programs may need to evolve to assess these competencies rather than code-writing ability alone. ### Funding Model Implications **Documentation as Differentiator:** In a world where AI can generate basic functionality, comprehensive, high-quality documentation becomes a competitive differentiator. Commercial plugins may invest in documentation as part of their value proposition. This could drive innovation in documentation tooling and approaches. **Open Source Sustainability:** Open source projects without commercial backing struggle to maintain documentation. As documentation becomes more critical, this sustainability challenge intensifies. Funding mechanisms—grants, sponsorships, community-supported documentation teams—need development. **Consultant and Agency Opportunities:** Specialists in WordPress documentation strategy, AI optimization, and information architecture may find increasing demand. Agencies could offer documentation audits and optimization as services. This creates economic opportunities but also risks creating barriers to entry for smaller projects. **Platform Investment Requirements:** WordPress.org and Automattic may need to significantly increase investment in documentation infrastructure, tooling, and support. This includes: better documentation hosting, improved search and discovery, tools for testing AI discoverability, and support for translation and localization. **Value Attribution:** Measuring the ROI of documentation investment remains challenging. As documentation becomes more critical, developing robust attribution models—connecting documentation quality to developer acquisition, support cost reduction, and code quality improvement—becomes essential for justifying continued investment. ## 🧠 Learning Styles Assessment **Reading Level Estimate:** Using the Flesch-Kincaid Grade Level formula on the main content section: approximately **Grade 12-13** (high school senior to first-year college level). This is appropriate for the target audience of professional developers and documentation specialists, but potentially challenging for junior developers or non-native English speakers. Consider providing executive summary sections at lower reading levels (Grade 8-10) for accessibility. #### 👀 Visual learners **Present in current content:** - Minimal visual elements in transcript format - Code example mentioned (WooCommerce local setup) but not visually represented - Search result sidebar description provides some visual context **Improvements needed:** - Architecture diagram showing relationship between LLMs, search engines, and documentation - Flowchart illustrating documentation decision tree (when to auto-generate vs. hand-craft) - Before/after comparison of documentation optimized for AI vs. traditional documentation - Screenshot examples of good cross-linking patterns - Visual representation of documentation genres (guides vs. tutorials vs. references) with characteristics - Infographic summarizing key best practices - Captions or annotations on video screenshots showing specific elements discussed #### 🔊 Aural learners **Present in current content:** - Original video with audio available - Conversational tone in transcript preserves spoken quality - Natural speech patterns and pauses indicated **Improvements needed:** - 3-5 minute audio summary extracting key insights - Podcast-style discussion elaborating on main themes - Text-to-speech friendly formatting with clear pronunciation guides for acronyms (GEO, AEO, MCP) - Speaker notes or commentary track explaining context not clear from audio alone - Audio clips highlighting particularly important quotes that could be shared standalone #### 🗣️ Verbal learners **Present in current content:** - Clear definitions of SEO, GEO, AEO terminology - Analogies present ("AI systems are basically really smart search engines in a trench coat") - Examples illustrating abstract concepts (WooCommerce local setup query) - Explicit comparisons between different documentation types **Improvements needed:** - Glossary section defining all technical terms (LLM, MCP, progressive disclosure, data structures, etc.) - More extensive use of analogies comparing documentation to familiar systems - Plain-language explanations before introducing technical terminology - Story-driven examples showing developer journey from discovering plugin through becoming contributor - Comparison tables (e.g., auto-generated vs. human-crafted, SEO vs. GEO) - Callout boxes defining terms inline when first introduced #### 🧩 Kinesthetic learners **Present in current content:** - Minimal hands-on elements in current format - Q&A section suggests practical application questions - Some step-by-step implications (auto-generate references, write guides manually) **Improvements needed:** - Interactive checklist for auditing documentation AI-readiness - Step-by-step tutorial for implementing structured data markup in WordPress docs - Hands-on exercise: "Take one piece of your documentation and optimize it for AI" with before/after review - Documentation sandbox where learners can experiment with different structures and see AI parsing results - Small experiments: "Query ChatGPT about your plugin 10 times and analyze what documentation it cites" - Worksheet for planning multi-genre documentation architecture - Reproducible task: "Auto-generate API reference documentation from your codebase" #### 🧠 Logical learners **Present in current content:** - Clear cause-effect relationship: poor documentation → AI can't discover → lost developer audience - Logical progression from problem statement through solution strategies - Data point provided (WooCommerce search example showing cited sources) - Structured argumentation in main content section **Improvements needed:** - Decision tree for documentation strategy choices based on audience, resources, and goals - RACI matrix showing who's responsible for different documentation types - Timeline showing evolution of documentation practices from pre-AI to AI-optimized future - KPI dashboard specification (what to measure and why) - Error budget framework for documentation maintenance - Causal diagram showing relationships between documentation quality, AI performance, developer acquisition, and support burden - Formal logic representation of key arguments - Cost-benefit analysis framework for documentation investment decisions #### 🧑‍🤝‍🧑 Social learners **Present in current content:** - Q&A session demonstrates community interaction - References to WordCamp US and community talks indicate social learning context - Implicit invitation to discussion through open-ended questions **Improvements needed:** - Discussion prompts for documentation team meetings or community forums - Cohort study guide for groups learning documentation strategy together - Peer review rubric for evaluating documentation quality - Collaborative exercise: "Documentation sprint planning for your team" - Q&A session facilitation guide with suggested questions and discussion topics - Case studies featuring multiple teams' approaches with opportunities for comparison - Community forum integration where learners can ask questions and share experiences - Moderated discussion series on evolving documentation practices #### 🧘‍♀️ Solitary learners **Present in current content:** - Comprehensive written content enables independent study - Self-assessment implicit in questions section - Individual reflection invited through analytical framework **Improvements needed:** - Reflection prompts after each major section: "How does your current documentation compare?" - Self-check quiz with answers: "Test your understanding of AI-friendly documentation principles" - Journaling questions: "What documentation gaps exist in your project? Why have they persisted?" - Worksheet for individual documentation strategy planning - Self-paced learning path with milestones and checkpoints - Solo exercises that don't require team coordination - Private assessment tools for evaluating own documentation quality - Reading list for deeper independent study #### 🌿 Naturalistic learners **Present in current content:** - Ecosystem thinking present (WordPress community, plugin ecosystem) - Organic evolution of practices discussed - Limited direct nature analogies **Improvements needed:** - Documentation ecosystem metaphor: treating documentation as a living system that needs feeding, pruning, and care - Lifecycle thinking: birth (new feature docs), growth (expansion and cross-linking), maturity (optimization), death (deprecation and archival) - Sustainability framework: what makes documentation practices sustainable long-term? - Environmental impact consideration: does better documentation lead to more efficient code, less compute waste? - Analogies to natural systems: documentation as mycelial network connecting knowledge nodes - Green tooling links: documentation generators with minimal environmental footprint - Patterns from nature applied to information architecture (e.g., fractal structure, redundancy, interconnection) ## 📊 Accessibility Assessment #### Screen reader semantics **Present:** - Markdown structure implies heading hierarchy - Lists used for organizing information - No visual-only information in transcript content **Improvements needed:** - Explicit ARIA landmarks if converting to HTML (`<nav>`, `<main>`, `<aside>`) - Alt text for any diagrams or screenshots added to visual learning section - Language attribute on code examples (`lang="php"`, `lang="javascript"`) - Descriptive headings that make sense out of context (screen reader users often navigate by headings) - Table of contents should use proper nav element with aria-label - Video embed should include proper caption/transcript association - Ensure any interactive elements have proper roles and states #### Keyboard navigation **Present:** - Markdown/text format is inherently keyboard accessible - No interactive elements requiring mouse **Improvements needed:** - If converting to web format, ensure skip links to main content and major sections - Video player must be fully keyboard operable (play/pause, seek, volume, captions) - Any collapsible sections must be keyboard accessible - Tab order must follow logical reading order - Focus indicators must be clearly visible (meeting 3:1 contrast ratio) - No keyboard traps in any embedded components - Ensure correct tabindex use (avoid positive tabindex values) #### Contrast and readability **Present:** - Plain text has inherent high contrast - Markdown syntax provides structure without color dependency **Improvements needed:** - If adding syntax highlighting, ensure code comments meet 4.5:1 contrast - Any colored callout boxes must maintain 4.5:1 text contrast - Link text must meet contrast requirements against background - If using color to convey meaning (e.g., red for errors), also use icons or text - Large text (18pt+ or 14pt+ bold) can use 3:1 contrast minimum - Line height should be at least 1.5 times font size - Paragraph spacing at least 2 times font size - Consider recommending dark mode alternative with appropriate contrast #### Text resizing and reflow **Present:** - Markdown naturally reflows - No fixed-width containers in current format **Improvements needed:** - Ensure content reflows at 200% zoom without horizontal scrolling (WCAG 1.4.10) - No clipping of content when zoomed - Avoid pixel-based font sizes; use rem or em units - Support prefers-reduced-motion for any animations (particularly important if adding interactive diagrams) - Test with browser zoom and text-only zoom - Ensure code blocks wrap or scroll vertically rather than horizontally - Responsive breakpoints must maintain readability at all sizes #### Media and captions **Present:** - Transcript provided (excellent accessibility practice) - Video available on WordPress.tv **Improvements needed:** - Captions on original video should be checked for accuracy (auto-captions often have errors) - Provide downloadable transcript in multiple formats (TXT, PDF, DOCX) - Audio descriptions needed if video includes visual information not conveyed in audio (slides, demos, gestures) - Ensure video player doesn't autoplay (WCAG 1.4.2) - Provide audio-only option alongside video for bandwidth-constrained users - If adding supplementary video content, include comprehensive captions and transcripts - Consider providing summary audio that covers key points for aural learners #### Forms and interactions **Present:** - No forms in current content **Improvements needed:** - If adding interactive elements (checklists, assessments): - All form fields must have associated labels - Error messages must be programmatically associated with fields - Inline validation should not remove context when errors appear - Touch targets must be at least 44x44 pixels (mobile) - Provide clear instructions before form, not only in placeholder text - Success messages must be announced to screen readers (use aria-live regions) - Forgiving input patterns (accept multiple date formats, etc.) - Clear error recovery paths - Consider accessible toast/notification patterns for feedback #### Standards reference **WCAG 2.2 AA Criteria Gaps:** - **1.1.1 Non-text Content:** Need alt text for any images, diagrams, charts added - **1.2.1 Audio-only and Video-only:** Video has transcript, but would benefit from audio description if visual information is critical - **1.4.3 Contrast:** Must verify any added visual elements meet 4.5:1 contrast - **1.4.10 Reflow:** Must ensure web version reflows at 320px width - **2.1.1 Keyboard:** Must ensure all added interactive elements are keyboard accessible - **2.4.1 Bypass Blocks:** Need skip links if creating web version with repeated navigation - **2.4.6 Headings and Labels:** Some headings could be more descriptive - **3.1.2 Language of Parts:** Need lang attributes for any code examples in other languages - **3.2.3 Consistent Navigation:** Ensure consistent navigation patterns if part of larger site - **3.3.2 Labels or Instructions:** Any future interactive elements need clear instructions - **4.1.3 Status Messages:** Any dynamic content updates must be announced **Current Accessibility Strengths:** - Semantic HTML structure (implied by Markdown) - Transcript availability - No reliance on color alone - Clear language and structure - Keyboard-accessible by default in current format ## 🌍 DEIB Assessment #### Cultural breadth **Present:** - WordPress is inherently global platform, acknowledged implicitly - WooCommerce example familiar to international audience - Technical content is relatively culturally neutral **Improvements needed:** - Examples beyond US-centric context (WordCamp US, Google-centric SEO) - Acknowledge documentation challenges for non-English languages - Include case studies from plugins/themes serving diverse markets - Discussion of documentation localization strategies - Translation links for key documentation (not just English-first approach) - Cultural context for developer psychology (independence/self-direction may be culturally influenced) - Examples of AI systems beyond US-based (Baidu, European alternatives) - Community review process that includes voices from multiple regions #### Inclusive language **Present:** - Gender-neutral language used throughout ("developers" not "guys") - No unnecessarily gendered examples - Technical jargon defined in context **Improvements needed:** - Plain-language summary section at lower reading level for broader accessibility - Glossary with definitions not assuming US tech industry context - Avoid idioms that don't translate well ("game the system," "trench coat" metaphor) - Define acronyms on first use, every time (not assuming familiarity) - Consider that "everyone knows what SEO is" may not be true globally - Expand abbreviations in ways that aid screen readers and translation - Avoid cultural assumptions about education background or technical training - Provide context for references to specific events (WordCamp US attendance) #### Neurodiversity support **Present:** - Clear structure with headings - Lists used to organize information - Consistent formatting patterns **Improvements needed:** - Increase heading frequency (more H3/H4 subheadings for chunking) - Use icons alongside text labels for major sections (visual anchors) - Predictable patterns throughout (each section uses similar structure) - Content warnings if including stressful topics (job displacement, economic disruption) - Avoid sensory language that assumes neurotypical experience - Provide multiple entry points to content (executive summary, deep dive, case studies) - Use consistent terminology (don't switch between "AI assistant" and "LLM" without noting they're equivalent) - Break very long paragraphs into shorter chunks - Use white space generously - Option to collapse/expand sections for readers who need to control information density #### Representation **Present:** - Speaker identity not specified in transcript - No demographic information about examples used - Focus on technical content minimizes need for representation in examples **Improvements needed:** - When discussing developer demographics, include diverse perspectives - Examples should feature developers with various identities where relevant - Avoid defaulting to assumed "typical developer" stereotypes - Quote and cite diverse voices in documentation field - Case studies should include projects led by underrepresented groups - Imagery (if added) should show diverse developers - Alt text should note diversity appropriately when relevant to content - Avoid assumptions about economic resources (not everyone has access to paid AI tools) - Acknowledge different paths into development (bootcamps, self-taught, formal education, career changes) #### Psychological safety **Present:** - Generally respectful framing - Acknowledges economic disruption compassionately ("we're not all excited about that") - Q&A format shows openness to questions **Improvements needed:** - Content warning about AI's impact on content economics upfront - Explicitly validate concerns about AI disruption - Acknowledge that documentation professionals may feel threatened by automation discussion - Community guidelines for any discussion forums - Clear escalation path for questions that involve sensitive topics - Moderated Q&A with focus on constructive discussion - Avoid framing that suggests "obvious" knowledge (shaming those who don't know) - Acknowledge that some developers may not want to use AI tools (respect choice) - Discussion of automation should include transition support resources - Frame challenges as system/structural issues, not individual inadequacy #### DEIB Strengths - Technical focus reduces some DEIB challenges - Open source context generally inclusive - No gatekeeping language around who can create documentation #### DEIB Gaps Requiring Attention - Assumed cultural context (primarily US/English-speaking tech industry) - Economic assumptions (resources for paid tools, time for contribution) - Educational assumptions (familiarity with specific technologies) - Language accessibility (could be challenging for non-native English speakers) - Neurodiversity considerations need explicit design - Global perspectives underrepresented ## ✅ Logical Validity #### Strong reasoning **1. Causal reasoning: Documentation → AI citation → Developer adoption** - **Location:** Summary and main content sections - **Strength:** Establishes clear chain: Well-structured docs get indexed by search → AI systems cite indexed content → Developers discover and adopt platform - **Evidence:** Concrete example of WooCommerce local setup query showing cited sources - **Why strong:** Uses observable mechanism (AI search behavior) rather than speculation - **Clarification needed:** Would benefit from quantitative data on correlation between documentation quality and adoption rates **2. Deductive reasoning: LLM limitations necessitate documentation** - **Location:** "The Continued Value of Documentation" section - **Premises:** (1) LLMs have training cutoffs, (2) New features emerge constantly, (3) LLMs need current information - **Conclusion:** Therefore documentation remains essential - **Why strong:** Valid logical structure; premises are factual and conclusion follows necessarily - **Clarification needed:** Could strengthen by addressing counterargument: "But can't LLMs be continuously retrained?" **3. Analogical reasoning: Traditional SEO principles still apply to AI discovery** - **Location:** "From SEO to GEO" section - **Analogy:** Just as content needed to rank in Google to be discovered, it needs to be findable for AI systems - **Why strong:** AI systems explicitly use search algorithms, making analogy concrete rather than metaphorical - **Clarification needed:** Should acknowledge where analogy breaks down (AI can synthesize across sources differently than search result lists) **4. Inductive reasoning: Auto-generation works well for references, not tutorials** - **Location:** "Balancing Auto-Generation and Human Craft" section - **Pattern:** Observes that reference docs have characteristics (structured, formulaic, comprehensive) that suit automation while tutorials have characteristics (narrative, pedagogical, contextual) that require human craft - **Why strong:** Based on observed properties of documentation types and demonstrated capabilities of automation tools - **Clarification needed:** Would benefit from empirical data showing quality differences **5. Conditional reasoning: If developer-focused, then specific documentation approach required** - **Location:** "Developer-Specific Considerations" section - **Conditional:** IF audience is developers THEN documentation must support self-service, avoid marketing friction, enable independence - **Why strong:** Grounded in understanding of developer psychology and behavior patterns - **Clarification needed:** Should acknowledge this is generalizing and individual developers vary #### Fallacies **1. Appeal to authority (mild)** - **Location:** References to Danny Sullivan's talk: "Google's search liaison gave a comprehensive talk" - **Weakness:** While Sullivan is indeed authoritative, the argument should stand on its merits beyond his endorsement - **Fix:** Include the specific evidence or reasoning Sullivan provided, not just cite his position - **Severity:** Minor—authority is relevant in this case and used as supporting rather than sole evidence **2. Hasty generalization (potential)** - **Location:** Developer psychology section: "Developers tend to be independent, self-starting, and averse to content that feels like a sales pitch" - **Weakness:** Generalizes from subset to entire category without acknowledging variation - **Fix:** Add qualifier: "Many developers, particularly in open source communities, tend to..." and note exceptions - **Severity:** Moderate—could lead to documentation that doesn't serve all developer segments **3. False dichotomy (implied)** - **Location:** Auto-generation vs. human craft discussion - **Weakness:** Presents these as binary choice when spectrum of approaches exists (human-edited auto-generation, AI-assisted human writing, etc.) - **Fix:** Explicitly acknowledge hybrid approaches and their trade-offs - **Severity:** Minor—text doesn't strictly claim binary, but could be read that way **4. Post hoc ergo propter hoc (potential)** - **Location:** Implicit in recommendations without empirical backing - **Weakness:** Some recommendations assume causation from correlation (e.g., AI systems cite documentation → Therefore optimizing documentation will increase citations) - **Fix:** Acknowledge these are working hypotheses pending empirical validation; hence the Hypotheses section provides testable predictions - **Severity:** Moderate—should be clear about what's proven vs. plausible **5. Slippery slope (avoided but risked)** - **Location:** Discussion of economic shifts - **Potential weakness:** Could have claimed "If AI systems don't cite your docs, your entire project will fail" - **Actually handled well:** Speaker acknowledges change without catastrophizing: "economic structures of the web are shifting, and we're not all excited about that, but there is still gonna be value" - **Severity:** N/A—fallacy was avoided **6. No true Scotsman (potential in Q&A)** - **Location:** Developer psychology discussion - **Potential weakness:** Could dismiss developers who don't fit pattern as "not real developers" - **Actually handled well:** Speaker acknowledges "if your software is more end user" different rules apply - **Severity:** N/A—fallacy was avoided #### Tone of voice **Overall tone: Pragmatic, collaborative, cautiously optimistic** **Characteristics:** 1. **Conversational authority:** Speaker uses casual language ("Hey," "you know") while demonstrating expertise. Example: "So yes, the economic structures of the web are shifting, and I don't think we're all excited about that, but there is still gonna be value..." 2. **Validation of concerns:** Acknowledges disruption and uncertainty without minimizing. Example: "We're not all excited about that" validates audience's potential anxiety about AI impact. 3. **Action-oriented:** Focuses on practical responses rather than theoretical hand-wringing. Example: "So let's talk about where the value aligns" moves from problem to solution. 4. **Humble expertise:** Makes claims without overstating certainty. Example: "I think" appears frequently, acknowledging these are informed opinions not absolute truths. 5. **Community-minded:** References shared context ("Did anybody here go to WordCamp US?") and positions content as synthesis of community wisdom, not individual authority. 6. **Realistic about complexity:** Doesn't oversimplify. Example: Discussion of documentation types acknowledges different genres require different approaches. 7. **Respectful of audience knowledge:** Explains when needed but doesn't over-explain. Example: "Everyone knows what SEO is, right?" acknowledges shared baseline while still defining it. **Tone strengths:** - Accessible without being condescending - Honest about uncertainty and change - Encouraging without being pollyannaish - Practical without being prescriptive **Tone weaknesses:** - Occasional filler words ("um," "sort of") could be edited for written content while preserving conversational feel - Some assumptions about shared context that may not hold for all audiences - Could be more explicit about limitations of speaker's own knowledge/experience ## 🛡️ DARVO Analysis **Context:** This talk does not involve accusations or defensive postures typical of DARVO patterns. The speaker is not responding to criticism or attempting to deflect blame. However, analyzing the rhetoric through this lens can identify any inadvertent defensive framing or attempts to minimize legitimate concerns. ### Deny **Not present in significant ways.** The speaker acknowledges rather than denies challenges: - Acknowledges economic disruption: "the economic structures of the web are shifting, and I don't think we're all excited about that" - Acknowledges uncertainty: frequent use of "I think" and conditional language - Acknowledges LLM limitations rather than overselling AI capabilities **Minor instance (not problematic):** - Potential minimization: "there is still gonna be value in putting fresh, relevant content forward on AI" could be interpreted as minimizing extent of disruption to content creators - **Analysis:** This is reassurance rather than denial—speaker is providing hopeful perspective, not denying that significant change is occurring - **Verdict:** Not DARVO; appropriate balance of acknowledging concern and providing constructive path forward ### Attack **Not present.** The speaker does not attack questioners, skeptics, or those with concerns about AI impact. The Q&A section shows respectful engagement with questions, even when they might challenge the talk's premises. **Tone analysis:** - Validates audience concerns rather than dismissing them - Responds to questions with substantive answers, not deflection - Acknowledges limitations of own recommendations: "if your software is more end user... then that might be different, you know?" **Verdict:** No attack rhetoric present. ### Reverse Victim/Offender **Not present.** The speaker does not position themselves or documentation creators as victims of unreasonable demands from AI skeptics or others. There's no attempt to reframe those concerned about AI's impact on content creation as the "real" problem. **Counter-evidence:** - Speaker aligns with audience concerns about economic disruption - Positions documentation creators as empowered to adapt, not as victims - Does not blame developers for changing consumption patterns - Does not frame AI companies as villains, but as reality to adapt to **Verdict:** No victim/offender reversal present. ### Emotional Cues and Rhetoric **Emotional strategies used (appropriately):** 1. **Solidarity:** "We're not all excited about that" uses inclusive "we" to show speaker shares audience concerns 2. **Reassurance:** "Don't feel bad about it" directly addresses potential anxiety about documentation value 3. **Empowerment:** Action-oriented language ("let's talk about," "so what can we do") frames audience as agents, not victims 4. **Validation:** Acknowledges that concerns are reasonable before providing solutions 5. **Honest uncertainty:** Frequent hedging ("I think," "probably," "kind of") shows intellectual humility rather than false confidence **Rhetoric analysis:** - **Ethos:** Builds credibility through community references (WordCamp US, WooCommerce experience), humility, and practical knowledge - **Pathos:** Acknowledges emotional reality of change while providing hopeful path forward; doesn't manipulate fear or anxiety - **Logos:** Grounds arguments in examples, logical reasoning, and observable patterns ### Related Fallacies (from Logical Validity section) **No toxic patterns linking to DARVO:** - The mild appeal to authority (Danny Sullivan) is not used defensively - The potential for hasty generalization about developers is not used to dismiss concerns or attack critics - The speaker explicitly invites questions and engages respectfully with challenges ### Overall DARVO Assessment **Finding: No DARVO pattern present.** This talk exemplifies healthy discourse about challenging change: - Acknowledges disruption honestly - Validates concerns - Provides constructive adaptation strategies - Invites dialogue and questions - Shows intellectual humility - Does not position speaker or any group as victim - Does not attack skeptics or those with concerns - Does not minimize real challenges while still offering hopeful perspectives **Why this matters:** DARVO analysis is typically relevant when examining defensive rhetoric in conflict situations. Its absence here indicates the speaker is engaging constructively with a challenging topic rather than defensively protecting a position or deflecting legitimate criticism. This is the appropriate stance for an educational session exploring evolving best practices. ## 🎯 Conclusion Developer documentation faces a fundamental inflection point. The rise of AI-assisted development doesn't obsolete documentation—it transforms it from optional developer experience enhancement to critical infrastructure for platform discoverability and adoption. As AI systems increasingly mediate between platforms and developers, documentation becomes the primary mechanism by which your APIs, hooks, and patterns enter the knowledge ecosystem. The strategy forward is clear: maintain freshness, embrace structure, balance automation with human craft, and design for both human and AI consumption. Auto-generate precise reference documentation that explicitly defines parameters, return types, and data structures—this is where AI systems excel at parsing and where developers need unambiguous truth. Preserve human authorship for guides and tutorials where pedagogical design, narrative flow, and contextual understanding create genuine learning experiences. Traditional SEO principles remain relevant because modern AI systems are fundamentally hybrid—they blend pre-trained knowledge with real-time search of the open web. Your documentation must be discoverable by search algorithms to be accessible to AI assistants. The emerging terminology (GEO, AEO, LLM-EO) describes the same foundational challenge: making content findable and parseable. Documentation architecture matters as much as content. Extensive cross-linking between guides, tutorials, and references helps both humans navigate and AI systems understand relationships. Progressive disclosure supports developers from first encounter through deep expertise. Information hierarchy must be intentional, not accidental. For developer audiences specifically, respect their psychology. They're independent, self-directed problem-solvers who will abandon platforms that interpose marketing friction between them and technical information. Everything must be available for self-service exploration. Documentation that feels like a sales funnel will drive developers away faster than missing documentation ever could. **Practical next steps:** 1. **Audit existing documentation** for AI discoverability: Is it structured? Fresh? Cross-linked? Semantically marked up? 2. **Implement auto-generation** for API references and hook documentation. This reduces maintenance burden while providing the explicit structure AI systems need. 3. **Invest in human-crafted guides** that explain the "why" and "when," not just the "what" and "how." This is where you build understanding that transcends function signatures. 4. **Measure and iterate.** Track which documentation AI systems cite. Monitor where developers get stuck. Let data guide priorities. 5. **Join the community conversation.** This challenge faces the entire ecosystem. Share what works, learn from others, contribute to standards development. The economic structures of the web are shifting, and that's unsettling. But in every period of disruption, those who adapt thoughtfully and quickly gain advantage. Documentation is no longer a post-launch afterthought—it's the foundation of discoverability in an AI-mediated development world. Invest accordingly. ## 🧱 Refactor Appendix ### 📚 Literature Split Pad ### LLMs require fresh documentation beyond training cutoffs > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "You know, limited to a certain amount of data, and we're always gonna have new information. We're always gonna have new data, we're always gonna have new ways to do things, new features, all that sort of stuff." LLMs have inherent cutoff dates in their training data, meaning they lack knowledge of recent features, APIs, and best practices. For current information to reach developers building on platforms, it must exist in discoverable, structured formats accessible through search. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#11:00) #xref #articleseed ID:rw_wptvai_001 ### AI systems blend search algorithms with pre-trained knowledge > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "They're still using search algorithms to find more recent relevant content and then blending that into a LLMs note." Modern AI assistants don't rely solely on training data—they actively search the web for current information and synthesize it with pre-trained knowledge. This hybrid approach means traditional SEO principles remain relevant for AI discoverability. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#12:31) #xref ID:rw_wptvai_002 ### Human-valuable content serves AI systems well > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "If content is useful to humans, it will be useful to AI." Per Danny Sullivan's guidance and community consensus, the optimal strategy is creating genuinely helpful content for humans rather than attempting to game AI systems. Quality and utility for human readers translate directly to value for AI consumption. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#13:28) #share ID:rw_wptvai_003 ### Reference docs suit automation while tutorials require human craft > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11-10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "Reference guides are generally pretty easy to auto generate... but that middle step, the guides and tutorials, that's where the kind of human element and the intentionality behind it kind of come in." Documentation ecosystems should embrace both automation and human authorship strategically. API references, hooks, and function signatures can be auto-generated efficiently, providing precise structure. Guides and tutorials require pedagogical design and contextual understanding that only human authors provide effectively. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#44:23) #articleseed ID:rw_wptvai_004 ### Explicit parameter documentation improves AI performance > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "The more concrete we can say about input and output, the better AI is gonna do." Tools like Model Context Protocol demonstrate that explicit, structured documentation of inputs and outputs significantly improves AI system performance. Being very clear about parameters, return values, and data structures helps both human developers and AI assistants understand APIs correctly. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#45:10) #xref ID:rw_wptvai_005 ### Developers resist marketing friction in documentation > [!quote] [Developer Documentation in the Age of AI](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/) via [[WordPress.tv]]. Published 2025-11-10. Accessed 2025-11-10. > "Developers in particular have that marketing aversion. They're averse to anything that feels like a sales tactic." When targeting developers specifically, documentation must support self-service exploration without marketing friction. Developers are independent problem-solvers who quickly abandon platforms that interpose barriers between them and technical information. Everything must be available for self-directed learning. [view highlight](https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/#42:24) #articleseed ID:rw_wptvai_006 --- ### 🔖 Atomic Split Pad (Zettel Candidates) #### LLM training cutoffs necessitate discoverable documentation - LLMs lack knowledge of features and APIs released after their training data cutoff dates - Fresh documentation must exist in formats discoverable through search mechanisms - Links: [[AI Systems]] [[Documentation Strategy]] [[Information Architecture]] #### AI-mediated discovery makes SEO principles still relevant - AI assistants use search algorithms to find current content, then synthesize with pre-trained knowledge - Traditional SEO optimization helps documentation appear in AI-powered searches - Links: [[Search Engine Optimization]] [[AI Discovery]] [[Generative Engine Optimization]] #### Auto-generation suits structured reference docs better than narrative content - Reference documentation has formulaic structure and completeness requirements that suit automation - Tutorials and guides require pedagogical design and contextual storytelling that humans provide better - Links: [[Documentation Genres]] [[Automation]] [[Technical Writing]] #### Explicit type definitions improve both human and AI comprehension - Formally specifying parameters, return types, and data structures reduces ambiguity - Tools like MCP demonstrate AI performance improvements with explicit specifications - Links: [[Type Systems]] [[API Documentation]] [[Developer Experience]] #### Developer psychology requires friction-free documentation access - Developers value independence and self-service exploration - Marketing tactics and gated content drive developers away from platforms - Links: [[Developer Relations]] [[User Psychology]] [[Community Building]] #### Cross-linking density affects discoverability and comprehension - Extensive links between documentation types help humans navigate and AI systems understand relationships - Each documentation piece should acknowledge and connect to broader ecosystem - Links: [[Information Architecture]] [[Knowledge Graphs]] [[Navigation Patterns]] --- ### ✏️ Fleeting Queue (Extract by Selection) - Audit my plugin documentation for AI discoverability — measure search citation frequency — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Research auto-generation tools for PHP hook documentation — compare output quality — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Watch Danny Sullivan WordCamp US talk on SEO evolution — extract key principles — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Test ChatGPT/Claude citation patterns for WooCommerce docs — document what gets cited — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Design cross-linking strategy for documentation site — map all connection points — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Implement JSON Schema for complex return objects — improve AI and developer understanding — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Remove marketing gates from technical documentation — A/B test developer retention — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox - Create documentation quality scorecard — track freshness, structure, discoverability — context/https://wordpress.tv/2025/11/10/developer-documentation-in-the-age-of-ai/ #fleeting #inbox --- ## 🧰 Template Library (paste into Note Refactor → Refactored Note Template) [Templates as specified in original prompt - Fleeting, Literature, and Atomic templates remain exactly as provided in the user's document] ## Highlights - The landscape of developer education is changing. Every day more code is being written by modern generative AI, with users relying heavily on everything from chatbots to AI-infused IDEs to build new functionality on top of existing platforms like WordPress. However, LLM-generated code is only as the knowledge it has access to, and performs best when developers give it specific context for each task. So how should plugins and platforms be thinking about their approach to developer documentation when the behaviors of their target audience are shifting so dramatically? In this session, we’ll uncover the best approach to preparing your documentation for the coding workflows of the future. I’ll pull together insights from around the community, look at the new frontiers like GEO, and evaluate the best practices that are still emerging for developer documentation in the age of AI. ([View Highlight](https://read.readwise.io/read/01k9r8c2g49aptqekj06s7a6de))