Talk:Wikimedia Technical Documentation Team

Welcome!
Hi, all! Welcome to the team page for the newly formed Wikimedia Foundation Technical Documentation Team. Over the next few weeks, we'll be working to set up our team practices and plan our upcoming work. APaskulin (WMF) (talk) 21:35, 14 June 2023 (UTC)

Tech Docs update June 16, 2023
Hi everyone, This is the first in a series of twice-monthly updates to share what the Tech Docs Team has been working on. For more details, you can follow along on our Phabricator workboard.


 * Documentation metrics dashboard
 * We continued building the underlying functionality for the MVP of the dashboard, including the ability to fetch and display lists of pages and support for left-to-right and right-to-left styles. We're working through some legal questions around open source licenses before we can publish the code, but we're hoping to have this issue resolved soon.


 * Team processes and practices
 * As a newly formed team, we began the process of setting up our team documentation, contact channels, and work management practices, including this page.


 * Content mapping and user journeys
 * We continued working on content mapping to identify missing landing pages for user journeys, focusing on analyzing landing pages for using open data and hosting tools.


 * Decision records
 * We started developing a standardized template for decision records. If you have feedback on the proposed template or on decision records in general, we'd love to hear from you on T338835.


 * Pywikibot documentation updates
 * As part of an ongoing project to update and streamline the Pywikibot documentation, we completed updates to the Pywikibot on Toolforge tutorial.


 * Wikimedia Developer Portal
 * A big thanks to User:Sushrith Bogi for fixing a link, and to User:BDavis (WMF) for setting up a CI check to improve the contributor experience.

APaskulin (WMF) (talk) 22:37, 16 June 2023 (UTC)

Tech Docs update June 30, 2023
Hi all, It's the last day of the quarter and the last day of the 2022-2023 fiscal year! Here's an update on what the Tech Docs Team has been working on recently. For more details, you can follow our Phabricator workboard.


 * Documentation metrics dashboard
 * We started work on opening the dashboard view and fetching metrics, including handling for namespaces, SQL queries, and rate limiting. We completed the legal review process to choose an open-source license for the project, so we're looking forward to setting up the code repository.


 * Decision records
 * We completed edits to the standardized template for decision records. It is now available at Documentation/Decision records. Feedback on the talk page and edits welcome!


 * API Portal, AQS 2.0, and RESTBase sunsetting
 * We continued support for documentation strategy for the AQS 2.0 and RESTBase sunsetting projects, and for API documentation in general. We updated the API Portal with a new structure that supports multiple APIs.


 * Cloud Services documentation information architecture
 * We completed initial designs for task-focused landing pages for the Cloud Services collection and a revised collection structure for the Toolforge docs.


 * Team processes and practices
 * We published a list of active projects to our team wiki page and made progress on defining project management processes and team lead role responsibilities.

APaskulin (WMF) (talk) 22:46, 30 June 2023 (UTC)

Tech Docs update July 14, 2023
Hi all, It's a new fiscal year and a new quarter! Here's an update on what the Tech Docs Team has been working on recently. For more details, you can follow our Phabricator workboard.


 * Documentation metrics dashboard
 * We set up the code repository for the dashboard on Wikimedia GitLab, including project documentation and decision records, and started adding pageview statistics to the default view.


 * Team processes and practices
 * We reviewed the drafts of our approach to projects, advising, and the team lead role and published the resulting processes to our team page on Office Wiki.


 * Cloud Services documentation information architecture
 * We re-scoped the remaining work on this project to focus on information architecture updates. We completed drafts of the proposed information architecture for both the Cloud Services and Toolforge collections and reviewed them within the team in preparation for requesting feedback from stakeholders.


 * Pywikibot workshop materials
 * As part of our work documenting workshop materials for Pywikibot, we completed and published reusable templates for creating workshop handbooks and self-study guides. Edits and feedback are welcome!


 * Conceptual framework for landing pages
 * We defined the scope of this project, updated the task in Phabricator, and moved it to in progress.


 * mediawiki.org project pages update
 * We kicked off a new project to update the pages in the project namespace here on mediawiki.org, starting by researching the existing pages and navigation.

APaskulin (WMF) (talk) 21:03, 14 July 2023 (UTC)

Tech Docs update July 28, 2023
Hi all, Here's the latest update from the Tech Docs Team. For more details, you can follow our Phabricator workboard.


 * Pywikibot workshop materials
 * This project is now complete! There are now templates and tasks in place to complete the remaining handbooks and self-study guides. These tasks would be great medium-sized documentation projects for anyone interested in working on new pages.


 * Cloud Services documentation information architecture
 * We completed the design document for restructuring the Toolforge and Cloud Services docs and shared it with the Cloud Services Team for feedback. We also continued work on the content audit for the Toolforge docs.


 * Team processes and practices
 * We published processes for handling ongoing maintenance responsibilities and task intake on Office Wiki.


 * Decision records
 * We updated the decision record template with quick and complete options to support different size decisions. Comments and edits welcome!


 * Wikimedia Developer Portal
 * Thanks to User:Dolphyb and User:BDavis (WMF) for submitting patches! The SignIt Firefox Extension is now a featured JavaScript project for contributors.

APaskulin (WMF) (talk) 23:06, 28 July 2023 (UTC)

Tech Docs update August 14, 2023
Happy August, everyone! Here's the latest update from the Tech Docs Team. For more details, you can follow our Phabricator workboard.


 * Team processes and practices
 * This project is almost complete. We completed the review of the process for ongoing maintenance work and resolved the task. The remaining work is to define a set of team values, which we're hoping to do in the next few weeks, schedules permitting. Most of the processes resulting from this project have been published to the Wikimedia Foundation's private wiki (Office Wiki) because the processes are very granular and specific to our team, but if anyone is interested in reading them, let us know and we can share them more widely.


 * Cloud Services documentation information architecture
 * We collected feedback on the proposed information architecture from the Cloud Services team, both synchronously and asynchronously, and shared an updated proposal based on their feedback. We're planning to share these proposals more widely on Wikitech soon to collect more feedback.


 * Data access docs strategy
 * This project remains in the research phase, but there is now a Phabricator task that you can subscribe to if you're interested in following along or sharing your ideas.


 * Documentation metrics dashboard
 * Work on the dashboard continues! We validated that the site can be run on Toolforge, continued work on testing the best way of displaying charts, and fixed bugs related to calling Wikimedia REST APIs. In addition, we completed some knowledge sharing within the team and are looking forward to starting code review for future changes.


 * Pywikibot collection update
 * We continued work on re-scoping this project, including declining a task that was too broadly defined to be actionable. As a team, we've been discussing what makes a good doc task. You can find (and add to!) our thoughts on Documentation/Contribute/Filing documentation tasks.


 * mediawiki.org project pages update
 * This project has officially moved from research to in progress. Check out the completed scope and project plan on the task. We're starting with resolving some open questions and cleaning up some historical references. Help with any of the unassigned subtasks is welcome!


 * Google Season of Docs
 * There's a conversation on Phabricator about restarting Wikimedia's participation in Google Season of Docs. This program could include any Wikimedia-related open-source project, so let us know if you have ideas for documentation projects that could be completed in around three months.

APaskulin (WMF) (talk) 23:23, 14 August 2023 (UTC)

Tech Docs update August 29, 2023
Hi everyone! Here's the latest update from the Tech Docs Team. For more details, you can follow our Phabricator workboard.


 * Team processes and practices
 * With the completion of our team values, this project is now complete! As is traditional with writing projects, we made a minor process change immediately after wrapping up this project: You can now see a list of our past projects on our team page. We look forward to iterating on these processes as a team going forward.


 * Cloud Services documentation information architecture
 * After wrapping up the feedback phase with the Cloud Services team, we shared the new information architectures for these docs for community feedback. This is an exciting milestone for this project! Please read the Toolforge proposal and the proposal for updating the Wikitech main page, and share your feedback on the respective task.


 * Documentation metrics dashboard
 * We continued work on displaying page views in the dashboard and started planning for deploying the dashboard to Toolforge once this first feature is complete. Although the dashboard won't have met its MVP requirements, we look forward to starting to experiment with it while development continues. We also started doing code review for changes to the project and found our first bug.


 * Pywikibot collection update
 * We drafted a proposal for managing documentation for Pywikibot scripts and shared it within our team for feedback. We look forward to sharing this proposal for feedback on Phabricator in the upcoming weeks.


 * mediawiki.org project pages update
 * Work on this project has officially started, with lots of discussion happening in Phabricator and on wiki. We updated pages to ensure that the dual licensing of (non-help namespace) content is documented correctly, as well as cleaning up references to completed projects and looking at how gadget processes are documented. If you're interested in documentation around gadgets and how we manage them on mediawiki.org, please check out Project:Gadgets, and share your feedback on the talk page.


 * Conceptual framework for landing pages
 * This project looks at how we can make landing pages, a key type of page on documentation wikis, more effective and consistent. We recently started work on this project again. You can follow along with the latest changes at Documentation/Patterns/Landing_page and Documentation/Cross-collection landing page, along with the other great resources at Documentation/Toolkit.

APaskulin (WMF) (talk) 00:32, 30 August 2023 (UTC)

Tech Docs update September 15, 2023
Hi everyone! Here's the latest update from the Tech Docs Team. The team is focusing on wrapping up our longer-running projects, as well as thinking about where we can advise on projects outside the team. Let us know if there are any projects, either within WMF or the wider movement, that would be interested in working with us. For more details about our current work, you can follow our Phabricator workboard.


 * Cloud Services documentation information architecture
 * New navigation templates for the Toolforge admin docs and user docs are now live, along with revisions to wikitech:Portal:Toolforge and wikitech:Help:Toolforge. In addition, we created and applied new category metadata for Category:Documentation types and Category:Programming languages. Start from the Wikitech main page to experience the new navigation flow!


 * Documentation metrics dashboard
 * After working through some issues in the build process, we deployed the first experimental version of the dashboard to Toolforge at techdoc-dashboard.toolforge.org. Keep in mind that this is our first version, so features and site design are still evolving. We also fixed a bug with CSS displaying incorrectly on mobile.


 * Pywikibot collection update
 * Part of the re-scoping process on this project has been looking at how we can establish more reliable processes for maintaining the docs instead of relying on time-consuming page audits. We've now published a proposal to Phabricator to clean up the Pywikibot scripts documentation by reducing duplication between MediaWiki.org and the generated documentation on doc.wikimedia.org. If you're interested in the Pywikibot docs, please review the proposal and add your feedback to the task. This project has now moved back to in progress while we complete the remaining page updates.


 * mediawiki.org project pages update
 * Work on this project has focused on documenting how categories are used on MediaWiki.org, as well as completing some minor category clean up. Check out Project:Categories to learn more. We're also still looking for feedback on Project:Gadgets from people who create or manage gadgets on MediaWiki.org.

APaskulin (WMF) (talk) 00:52, 16 September 2023 (UTC)

Tech Docs update October 2, 2023
Happy October everyone! The team has successfully wrapped up our remaining projects started before July 2023. Going forward, we'll be focusing on projects that address focus areas in this year's Wikimedia Foundation annual plan, as well as advising on initiatives around the Product and Technology department. For more details about our current work, you can follow our Phabricator workboard.


 * Cloud Services documentation information architecture
 * This project is now complete! A huge shoutout to everyone who gave feedback and contributed to this work. All the documentation updates and information architecture changes have been applied. Check out the new navigation for the Cloud VPS docs at wikitech:Portal:Cloud VPS and wikitech:Help:Cloud VPS, as well as updated versions of wikitech:Help:Cloud VPS project, wikitech:Portal:Toolforge/About Toolforge, and wikitech:Help:Toolforge/Quickstart. Further updates for these docs identified during this project have been opened as subtasks of T203131. Before formally completing this project, we're working on publishing a summary of the outcomes and guidance for future work on these docs.


 * Pywikibot collection update
 * Another project complete! With final interlinking improvements made to various Pywikibot wiki pages, the scope of this work is officially completed. Check out T320625 for a summary of the outcomes of this project.


 * Conceptual framework for landing pages
 * The scope of this work is now complete. As with several categories of documentation work, this topic is a continuing area of work, one the team will return to periodically. To complete this project, we created Documentation/Portal pages to provide guidance for creating pages that help readers navigate between technologies, in contrast to landing pages that navigate within a technology's docs. If you're interest in these topics and the types of pages useful for navigating documentation on a wiki, we'd love to hear from you. Before formally completing this project, we're working on publishing a summary of the outcomes.


 * mediawiki.org project pages update
 * Project:Categories has been finalized with a description of how categories work with translated pages on MediaWiki.org.

APaskulin (WMF) (talk) 23:10, 2 October 2023 (UTC)

Tech Docs update October 17, 2023
Hi everyone! Here's the latest update from the Tech Docs Team. The team is focusing on planning for new projects related to our team goals and the Wikimedia Foundation's annual plan. For more details about our current work, you can follow our Phabricator workboard.


 * Conceptual framework for landing pages
 * We formally completed this project by publishing the results. Check out this comment for a summary of our findings.


 * Cloud Services documentation information architecture
 * A summary of the results of this project have been published to commons:File:Cloud Docs Project Summary Q1 FY2023-24.pdf and Wikimedia Cloud Services team/Documentation guide, formally wrapping up this project.


 * Editing support for the frontend stable interface policy
 * We completed edits to Stable interface policy/Frontend, including improvements to organization, formatting, and language.


 * Data access docs and dataset docs
 * To help break up the scope of this work, we've split this project into two different scopes. Dataset docs refers to documentation for Wikimedia data, including information stored in DataHub. In contrast, data access docs help people discover and use that data. In the planning phase, we're focusing on identifying user stories and resolving open questions. These steps will help us prioritize which user stories to work on first and define short-term and long-term project goals.


 * Documentation metrics dashboard
 * As we continue to work on displaying available metrics, we made progress on displaying the number of page edits broken down by day.


 * Deployment pipeline documentation improvements
 * We kicked off a new project to improve the docs for the Wikimedia deployment pipeline, including GitLab, Kokkuri, and Blubber. We completed initial research, published a project plan to the task, and started conversations with users.


 * Replace jsduck with JSDoc3 across all Wikimedia code bases
 * Tech Docs is taking on this project to provide guidance on the priorities and requirements for the Wikimedia JSDoc theme, which enables the migration to JSDoc and support for ES6 in JavaScript codebases. To kick of this project, we started with initial research and conversations with stakeholders.


 * Document a MediaWiki quickstart workflow for contributors
 * Finally, we kicked off a project to evaluate an easy-to-use, container-free, quickstart workflow for setting up a local MediaWiki development environment. We published the goals, scope, and project plan to the task and started to collect research on Project:Development environments.

Leave a comment on this post if you're interested in getting involved with our work or sharing your experience with any of the technologies mentioned here! APaskulin (WMF) (talk) 22:00, 17 October 2023 (UTC)

Tech Docs update October 31, 2023
Hi everyone! Here's the latest update from the Tech Docs Team. For more details about our current work, you can follow our Phabricator workboard.


 * Data access docs and dataset docs
 * We made progress in the research and information-gathering phase, building understanding of the space and meeting with subject matter experts to try to narrow down priority focus areas. We met with 3 people from Data Platform Eng, Product Analytics and Data Products, started modeling and auditing the documentation for the pageviews dataset and its sources, and started compiling important concepts to make sure data access docs cover for those data sources.


 * Deployment pipeline documentation improvements
 * As part of the research phase of this project, we conducted four user research interviews with GitLab adopters within WMF. To help identify key docs and find documentation gaps, we started a high-level deployment pipeline overview doc.


 * Document a MediaWiki quickstart workflow for contributors
 * We started prototyping the workflow for this process at User:APaskulin (WMF)/Sandbox/Local quickstart, including collecting feedback and testing on Mac, Ubuntu, Debian, and Fedora. For more details about the progress and learnings, see the Phabricator task.


 * AQS 2.0 documentation
 * We made progress on the AQS 2.0 documentation maintainer documentation on Wikitech, as well as the user-facing API documentation. OpenAPI specifications for some AQS 2.0 services are now being served publicly via API endpoints. We're planning to serve these specs in human-readable formats using open-source tooling. See the API spec reader for an example.


 * Wikimedia Developer Portal
 * We deployed the latest updates with support from the Cloud Services team, including bug fixes for Arabic translations, and merged two volunteer-submitted patches.

APaskulin (WMF) (talk) 23:23, 31 October 2023 (UTC)

Tech Docs update November 20, 2023
Hi everyone! Here's the latest update from the Tech Docs Team. For more details about our current work, you can follow our Phabricator workboard.


 * Deployment pipeline documentation improvements
 * We completed the user research phase of this project, created a project plan with proposed improvements and timelines, and reviewed it with the Release Engineering team. In addition, we made progress on the high-level deployment pipeline overview doc.


 * Document a MediaWiki quickstart workflow for contributors
 * We completed the document, including adding instructions for Windows, fixing a bug in the MediaWiki install script on Windows, collecting and incorporating feedback, and moving the page to Local development quickstart before asking for broader feedback.


 * Replace jsduck with JSDoc3 across all Wikimedia code bases
 * We drafted a set of recommendations to move this project forward, shared it with stakeholders for their feedback, and posted an update to the task to request feedback from participants there.


 * Data usage documentation
 * Work in this area will proceed in collaboration with the Research and Data Platform Engineering teams as we work on creating new content to help researchers navigate our data landscape, while coordinating with changes to the underlying data infrastructure and documentation strategy. Following researching potential areas of documentation impact and meeting with project owners and subject matter experts, we initiated a project to collaborate with Research on creating an introduction to Wikimedia open data. To make it easier to navigate the terminology used in this project, we adopted "data usage" as a term to replace "data access".


 * Define dataset documentation strategy
 * We met with stakeholders and product owners and determined that the first project to be prioritized in this area will be redesigning the Data Platform docs on Wikitech. As a first step, we completed copyedits and content review for the Data Platform team overview doc and resumed work on a data docs content audit, now focused specifically on Data Platform docs.


 * Wikimedia developer satisfaction survey
 * We designed documentation-related survey questions to include in the upcoming survey from Release Engineering.

APaskulin (WMF) (talk) 21:39, 20 November 2023 (UTC)