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 phab: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 phab: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 phab: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 wikitech: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)

Tech Docs update December 11, 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 published the project plan to the parent task and completed the review of existing deployment pipeline docs. We completed the draft of the deployment pipeline overview doc and are in the process of reviewing it with the team. We're also making progress on the repository of configuration file examples.

Document a MediaWiki quickstart workflow for contributors

We shared Local development quickstart for wider feedback and responded to questions on the talk page. We're currently testing the quickstart as part of the WMF-internal MediaWiki Code Jam.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We updated information about this project on Phabricator and MediaWiki.org, and we sent a project announcement to relevant channels requesting feedback. In collaboration with WMF frontend teams, we started the process of incrementally moving the MediaWiki core docs to JSDoc. We also made several improvements to the theme, including releasing a new version.

Data usage documentation

We started a draft introducing Wikimedia open data that includes Research-focused learning goals and data user journeys. We will continue to build on this as we figure out how to structure the content.

Define dataset documentation strategy

We moved this project to stalled as we start work on the specific scope defined in phab:T350911.

Redesign Data Platform docs on Wikitech

We kicked off work on this project, including completing a review of existing docs and creating a content strategy. In collaboration with stakeholders, we started developing an information architecture for these docs.

APaskulin (WMF) (talk) 00:02, 12 December 2023 (UTC)

Tech Docs update December 21, 2023

Hi everyone! Here's the last 2023 update from the Tech Docs Team. Thanks for a great year! For more details about our current work, you can follow our Phabricator workboard.

Deployment pipeline documentation improvements

We completed the repository of configuration file examples and published a draft of the Deployment pipeline overview on wiki.

Document a MediaWiki quickstart workflow for contributors

We finalized the Local development quickstart, removed the experimental banner, and added a link in the local installation section of How to become a MediaWiki hacker. Huge thanks to everyone who left feedback on the talk page, edited the guide, and submitted patches to improve the tooling! Initial results of the CodeJam survey show that several participants used a local installation for their development environment (6 participants using a local installation versus 7 using Docker) and that they were generally satisfied with it (averaging 4 out of 5). We'll be finalizing and publishing these results next month before closing out this project.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We released a new version of the theme that includes significant improvements completed during the CodeJam week, including improvements to styles, responsiveness, and readability. In addition, we've made significant progress migrating MediaWiki core to JSDoc. To follow our progress and to help with migration, see phab:T352308. Check out the latest version of the docs on doc.wikimedia.org. To share your feedback about the site, please leave a comment on Talk:JSDoc WMF theme.

Data usage documentation

We made progress on finalizing the content of the data source tables (example) that will serve as important reference content about the datasets. We made progress on creating drafts of new overview pages for each of our major data families: traffic/readership, content, edits, and editors. We also started and shared a first draft of an attempt to map common research questions and terminology to canonical data sources, investigating presentation options for semantically complex tabular data on wiki.

Redesign Data Platform docs on Wikitech

We collaborated with stakeholders to create the next iteration of the information architecture for the Data Platform Engineering docs and share it with stakeholders. We made progress on the landing page draft as part of an iterative approach of starting with the complete set of content and progressing to revising landing pages and navigation for each subcollection. We also continued work on the content audit and made progress on adding categories for some of the topics that have the most content sprawl across wikis, such as Category:Pageviews and Category:Wikistats.

APaskulin (WMF) (talk) 19:03, 21 December 2023 (UTC)

Tech Docs update January 25, 2024

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.

Document a MediaWiki quickstart workflow for contributors

This project is now complete! We published the final results and findings to the Phabricator task.

Deployment pipeline documentation improvements

We completed the GitLab/Workflows/Deployment pipeline, including a diagram representing the process. The Release Engineering team is making progress on reviewing and updating the existing documentation, and we're shifting out focus to the structure of these docs.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We continued to make significant progress migrating MediaWiki core to JSDoc and making improvements to the theme. To follow our progress and to help with migration, see phab:T352308. Check out the latest version of the docs on doc.wikimedia.org. To share your feedback about the site, please leave a comment on Talk:JSDoc WMF theme.

Data usage documentation

Using information gathered in the research phase, we started writing an introduction to Wikimedia open data that covers existing content about the different types of data and contextualizes it for readers with no familiarity with the Wikimedia movement. We also worked on modeling the information architecture of data documentation across teams and projects.

Documentation metrics dashboard

We migrated the dashboard to use Blubber and Kokkuri for the tests CI pipeline. We also made progress on security and stability improvements, including a fix for parameter validation.

Redesign Data Platform docs on Wikitech

We researched the mediawiki_history dataset doc, working on understanding the different data products where that information is available so that we can assess the state of the documentation for this dataset.

AQS 2.0

We updated the planning and scope of remaining documentation work for AQS 2.0, including using the API spec reader tool to host an example of one of the new API specs. See phab:T288664.

Community outreach

We presented a session on the theory and best practices of technical documentation at the Wiki Mentor Africa virtual hackathon to over 90 participants. Check out the slides on Commons.

APaskulin (WMF) (talk) 16:33, 25 January 2024 (UTC)

Tech Docs update February 10, 2024

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

The Release Engineering team has completed reviewing and updating the existing critical path documentation, and we're continuing to work on improving the structure of the docs.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We released v0.0.12 of the theme and applied it to the MediaWiki core docs, including clickable anchor links and fixes for syntax highlighting, line numbers, and readability. We're continuing to make progress migrating MediaWiki core to JSDoc and scoping remaining improvements to the theme. To follow our progress and to help with migration, see phab:T352308. Check out the latest version of the docs on doc.wikimedia.org. To share your feedback about the site, please leave a comment on Talk:JSDoc WMF theme.

Data usage documentation

We continued to work on content drafts, including starting to finalize a page structure that can be consistently applied across overview docs for the different data domains. We also drafted a proposal for related doc work for categorizing research studies.

Documentation metrics dashboard

We added statistics for number of edits, top editors, and number of major and minor (as well as small and large) edits. We rescoped the remaining work for the MVP to prioritize experimentation and learning.

Redesign Data Platform docs on Wikitech

We created categories on Wikitech to use as a basis for generating domain-focused landing pages and started categorizing pages based on current page content and structure.

Community outreach

We started co-planning a documentation project for the Wikimedia Hackathon in May with the African Wikimedia Technical Community. We also started plans to submit a project for Google Season of Docs 2024.

APaskulin (WMF) (talk) 00:58, 10 February 2024 (UTC)

Tech Docs update March 1, 2024

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 improvements to documentation structure. We also made progress on reviewing supporting deployment pipeline docs, including clarifying outdated pages and deduplicating documentation between Blubber’s generated and wiki docs.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We officially completed migrating all files in MediaWiki core to JSDoc! We also launched a new version of the homepage to help guide new developers. Check out the latest version of the docs. We agreed on a scope for remaining improvements to the JSDoc WMF theme for the v1.0 release and continued to work on fixes and improvements, including improving sidebar and code sample formatting and making the theme more robust to incorrectly used tags.

Data usage documentation

We completed the first draft of the Introduction to Wikimedia open data and shared with subject matter experts for review.

Redesign Data Platform docs on Wikitech

We continued work on categorizing pages ( ~160 out of ~285 pages completed so far), including creating new categories to capture additional data aspects.

Document your Tool hackathon project

We opened a task for the project, created a project page, and started curating tasks.

Season of Docs

We set up a project page, completed other launch tasks, sent announcements to communities, and started reviewing applications.

Wikimedia Developer Portal

We completed a review of all links in the portal, and merged a patch with fixes, including adding a contributing link for a Rust project.

APaskulin (WMF) (talk) 01:30, 2 March 2024 (UTC)

Tech Docs update March 22, 2024

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 review of GitLab documentation on mediawiki.org (phab:T352262). We also published and finalized a static site with automated configuration docs for Blubber.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We've made significant progress addressing remaining issues in the MediaWiki core JSDoc site and the WMF theme. We completed a review of the MediaWiki core JSDoc site for usability, consistency, and parity with the JSDuck site. We released v0.0.13 of the theme, including 13 fixes and enhancements, and we've continued to make progress submitting patches as we work towards our v1.0 release.

Data usage documentation

We opened subtasks to capture work to create three pages covering key concepts, data sources, and access methods for major data domains: Content, Traffic, and Contributing (T343146), and we collected reviews on drafts from subject matter experts.

Redesign Data Platform docs on Wikitech

We built out a set of sandbox wiki pages to help clarify the content framework and met with stakeholder to plan next steps.

Document your Tool hackathon project

We started work on tool-specific documentation guidelines.

Season of Docs

We continued to review applications and respond to questions (5 applications have been submitted so far).

APaskulin (WMF) (talk) 22:08, 22 March 2024 (UTC)

Tech Docs update April 12, 2024

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 resolved the remaining tasks, officially completing the project! This project resulted in improved documentation for the Wikimedia service release pipeline, which should enable new services to deploy faster. We also created a documentation site for Blubber (our container image-building tool) and a repository of service examples for new service developers to copy. A big thanks to everyone from RelEng for your work on this!

Replace jsduck with JSDoc3 across all Wikimedia code bases

We have continued to make progress towards releasing v1.0 of the JSDoc WMF theme, including merging 20 patches. These patches included adding a custom navigation feature, a sitemap, and improvements to organization and styles, as well as several bug fixes. With these features complete, we started integration testing to prepare for the release, identifying and submitting fixes for two bugs. We've also made progress completing the remaining cleanup tasks for the migration of MediaWiki core, including fixing links, descriptions, and documentation on wiki.

Redesign Data Platform docs on Wikitech

We created a project plan for completing this work in Q4 and shared it with stakeholders. To facilitate coordination, we created a working group of subject matter experts and set up a dedicated Slack channel. We shared the draft of the Discover data landing page for review and made progress on the Analyze data landing page.

AQS user documentation

We kicked off a new project to complete the AQS 2.0 user documentation. We created a project plan, researched and drafted two decision records for selecting the project approach and tooling, and started work on creating a style guide for the reference docs.

Document your Tool hackathon project

We published a draft of a guide to tool documentation and reviewed within the team. We also published a draft of hackathon participation instructions.

Season of Docs

We submitted the organization application to Google and were officially accepted into the program! We were one of 11 accepted organizations out of around 40 applications. We set up the administrative account for transferring funds with Open Collective and continued to review applications and respond to questions (8 applications have been submitted so far).

APaskulin (WMF) (talk) 00:02, 13 April 2024 (UTC)

Tech Docs update April 26, 2024

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.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We released v1.0 of the theme! This is a big milestone for the team and marks the completion of this project's scope of theme improvements. The 1.0 release includes the new custom navigation features, improvements to information organization, the new plugin system, and much more. We also continued to make progress on the remaining cleanup work for the MediaWiki core migration, merging 6 patches and opening 4 patches, including upgrading to v1.0 of the theme and implementing a custom navigation design to improve usability.

Data usage documentation

We published a draft of the data introduction doc on wiki. Feedback welcome! We also connected with the Research team for feedback and opportunities for collaboration.

Redesign Data Platform docs on Wikitech

We completed the draft of the Analyze data landing page and shared it for review, as well as making progress on the Publish data landing page. We also updated the content audit spreadsheet to align with the current structure and identified outlying pages

AQS user documentation

We reached team consensus on decisions for approach and tooling, and finalized decision records. We also completed a style guide to help with consistency for documentation creation and an initial draft of an information architecture for the docs site.

Document your Tool hackathon project

We finished post-review changes and officially published the new Tool Docs guide. We wrapped up the doc by linking to it from related pages and reaching out to maintainers for tools used as examples. We also created instructions for how to use Toolhub to find and review tool documentation and then use the Tool Docs Guide to review and improve docs.

Season of Docs

We continued to review applications and respond to questions as we approach the application deadline on Sunday. 15 applications have been submitted so far.

APaskulin (WMF) (talk) 20:11, 26 April 2024 (UTC)

Tech Docs update May 17, 2024

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.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We're continuing work on the remaining cleanup and migration tasks to complete this project. We merged over 20 patches to improve JSDoc in MediaWiki core and over 25 patches to improve the JSDoc WMF theme, including releasing version 1.0.1 of the theme with support for configurable globals. A big thanks to everyone who has contributed to these patches and to migrating remaining codebases to JSDoc!

Data usage documentation

We published a draft of Analyzing content on wiki. Feedback is welcome there or on the talk page for Research:Data introduction.

Redesign Data Platform docs on Wikitech

We completed the draft of Publish data, collected feedback, and iterated on it, including looking at consolidating Collect data with Publish data. We'll be drafting and iterating on these landing pages as a set before implementing them in the main namespace on Wikitech.

AQS user documentation

We completed tech writer review of the information architecture and set up the repository, tools, and build process for the docs site. We published a prototype site to Toolforge and shared it for early feedback while we investigate a content security policy issue on doc.wikimedia.org. We also made progress on updates to the API specs to confirm to the style guide.

Document your Tool hackathon project

This project was pitched and worked on during the hackathon in Tallinn. Thanks to everyone who contributed!

Season of Docs

We reviewed the proposals and selected our top proposal for this year's project. See Season of Docs/2024#Selected proposal. The project is now is progress! For updates, see phab:T358605.

APaskulin (WMF) (talk) 21:52, 17 May 2024 (UTC)

Tech Docs update June 7, 2024

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.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We're nearing completion of the cleanup work for migrating MediaWiki core, with several patches merged and submitted. We've seen some great progress on migrating extensions to JSDoc. A big thanks to @Novem Linguae who has done great work migrating extensions and organizing the project's remaining scope! As of today, only three extensions still need to be migrated, one of which is in progress. The JSDoc WMF theme has several patches still waiting on code review, and we're planning to release a new version of the theme in the next couple of weeks.

Data usage documentation

We added new sections and tables to the data introduction draft and worked on responding to community feedback. We also attended a research workshop on using Wikimedia open data to discuss these docs with users.

Redesign Data Platform docs on Wikitech

We reached a big milestone in this project by publishing the new landing pages in the main namespace: Data Platform, Discover data, Transform data, and Analyze data, as well as updating Data Platform Engineering to serve as a navigation page. Thanks to everyone who helped provide feedback! To learn about the remaining work for this project, see T350914.

AQS user documentation

We published example pages to the site and made progress on writing tutorials. We moved all spec update patches into team code review, and two spec updates were deployed to production. Check out this page to see the live API sandbox.

Community outreach

We submitted a proposal for a GLAM tools annotate-a-thon for WikiConference North America 2024. We also reviewed and submitted tool ratings for the Coolest Tool Award committee. As a reminder, you can see the progress on our ongoing Season of Docs project at See Season of Docs/2024/Proposal.

APaskulin (WMF) (talk) 23:25, 7 June 2024 (UTC)

Tech Docs update July 3, 2024

Hi everyone! This weeks marks the change between the 2023-2024 fiscal year and the 2024-2025 fiscal year. To see everything the team has accomplished this year, check out our list of past projects. Here's a summary of the work we've done recently and the project we've wrapped up as the fiscal year comes to an end. As always, for more details about our current work, you can follow our Phabricator workboard.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We completed the remaining cleanup work for the migration of MediaWiki core to JSDoc. We'll be tracking continuous improvements through the MediaWiki-Documentation and JavaScript tags in Phabricator. We also released v1.1.0 of the JSDoc WMF theme and updated several codebases, including MediaWiki core. This marks the end of work on the theme reported here. Further improvements will be tracked using the JSDoc WMF theme board. A big thanks to everyone who contributed to this release, especially Novem Linguae who has completed the migration of the CollaborationKit extension, made great progress on migrating the GuidedTour extension, and resolved several JSDoc-related ESLint warnings in MediaWiki core.

Data usage documentation

This project is now complete! Research:Data introduction is now available as a introduction to the basic concepts researchers and data scientists should know to start working with Wikimedia data, and Research:Data now includes navigation tools to help data consumers find data sources by domain. See details on individual subtasks for further improvements that can be incorporated into other workstreams. Final work stages included publishing content changes in response to community feedback, including adding tutorial and workshop content, templates, categories, and cross-references, and attending a research workshop on using Wikimedia open data to discuss these docs with users.

Redesign Data Platform docs on Wikitech

This project is now complete! We collaborated with Data Platform Eng team and stakeholders to finalize content deprecations and set the team up for ongoing doc maintenance. We created a navigation menu that mirrors the structure of the Data Platform landing page, and added it to the major content pages, and we deprecated and redirected existing Data Engineering content. The new docs are available at Data Platform . A big thanks to everyone who contributed!

AQS user documentation

The new docs site is now complete and available at wmdoc:analytics-api. We completed site content, conducted user research interviews, and iterated on the site based on feedback. We redirected AQS 1.0 docs to the new site and drafted an announcement to be sent to the analytics mailing list next week.

Community outreach

We participated in committee work to assess tool rankings and finalize votes for all Coolest Tool Award nominees. We also continued advising for the 2024 Google Season of Docs project.

APaskulin (WMF) (talk) 20:36, 3 July 2024 (UTC)

Tech Docs update July 17, 2024

Hi everyone! Welcome to the first team update of the 2024-2025 fiscal year! Here's a summary of the work we've done recently to kick off the new quarter. For more details about our current work, you can follow our Phabricator workboard.

Replace jsduck with JSDoc3 across all Wikimedia code bases

We reviewed and merged six patches for the WMF JSDoc theme, and submitted one patch to improve the docs in MediaWiki core. There are several tasks marked as needs further discussion on the theme workboard, so check out those tasks if you're interested in how the theme works.

AQS user documentation

With the site announced on the analytics mailing list, this project is now complete! As part of the project wrap-up, we helped add docs for a new API (Commons analytics) to the site and opened a pull request to remove the old reference docs from the RESTBase documentation.

Documentation metrics dashboard

We're restarting work on the dashboard this quarter! We released a new version and submitted a merge request to complete the MVP. We're looking forward to releasing version 1.0 by the end of July.

Metrics Platform documentation

We kicked off this project by researching existing docs and user case studies, meeting with stakeholder and subject matter experts, and publishing an initial project plan to Phabricator. Our first task is to update the top-level guide to creating an instrument to ensure that there is a clear, up-to-date process (T370335). To start this work, we reviewed the two existing guides and made a few updates to address critical friction points, including using section transclusion to remove 7,000+ bytes of duplicated content between the two pages to prevent content drift and including transcluded information about initial steps to plan an experiment.

Documentation metrics for MediaWiki

This is a new project focused on defining metrics to measure the health of the MediaWiki documentation as part of a effort to measure the overall sustainability of MediaWiki. We kicked off this project by formulating a project plan and gathering pre-existing docs and resources to inform how we scope and design the work, including identifying deliverables and research questions. We're planning to define the dimensions of tech docs quality, map available data signals to quality dimensions, and define the scope of what we want to measure. Stay tuned for more details!

Community outreach

We prepared and recorded award videos for Coolest Tool award ceremony. We also worked on planning for community outreach projects for this fiscal year. We're looking forward to sharing more about these initiatives.

APaskulin (WMF) (talk) 00:33, 18 July 2024 (UTC)

Tech Docs update August 1, 2024

Hi everyone! After taking some vacation, we're back with another update from the Tech Docs Team. For more details about our current work, you can follow our Phabricator workboard.

Documentation metrics dashboard

We deployed v1.0.0 of the dashboard, officially completing the MVP! Check out the live dashboard. (You can use PagePile ID 59125 to try it out!)

Metrics Platform documentation

For this project, we're continuing to focus on updates to wikitech:Metrics Platform/How to/Create First Metrics Platform Instrument. We consolidated it with a similar page and re-structured the page to follow a step-by-step process. We're looking to iterate on these improvements in the coming weeks and start testing the guide with users.

Documentation metrics for MediaWiki

We created and published a full project plan with goals, milestones, and projected timeline. We also started on-wiki documentation of the Research phase, including research questions, goals, and summary of findings so far from literature review and other information-gathering.

Documentation tools and processes research

To better support documentation work within the Movement, the Wikimedia Technical Documentation Team needs to understand the documentation tools and processes that are in use in different projects. We kicked off this project by researching the docs tools and processes used on Wikimedia GitLab.

APaskulin (WMF) (talk) 01:36, 3 August 2024 (UTC)

Tech Docs update August 21, 2024

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.

Metrics Platform documentation

We've made significant updates to wikitech:Metrics Platform/How to/Create First Metrics Platform Instrument, simplifying and clarifying the process. We completed a content audit and identified next steps for key supporting guides. You can find the next steps for this project in the project plan on phab:T329506. We also made several updates to wikitech:Metrics Platform and subpages to reduce duplicated content.

Documentation metrics for MediaWiki

We made progress towards resolving research question 1: Completed the literature review and synthesis of prior work related to quantitative technical documentation metrics. You can read the summarized findings at Wikimedia Technical Documentation Team/Doc metrics/Research#Literature review. We used these research findings to start an iterative design process with the Tech Docs team, completing a card sorting exercise to map documentation characteristics to metrics categories.

Documentation tools and processes research

We completed review of documentation tools in Toolforge-related repositories on GitLab, including checking over 200 repos out of 570 (T371671). Our next steps are to update the task with observed patterns and continue with other popular repos on GitLab before moving on to Gerrit.

Maintenance projects and docs support

We also completed several small tasks associated with maintenance projects and general docs support, including code review and improvements for the MobileFrontend JSDoc site, code review for a patch for the Developer Portal, and review for the AQS deployment guide.

APaskulin (WMF) (talk) 23:34, 21 August 2024 (UTC)

Tech Docs update September 13, 2024

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.

Metrics Platform documentation

This project has been paused lately due to team vacations, but work is now resuming. We're focusing on a process for documenting instruments, including how to make instrument information publicly accessible, and starting to work on consolidating Metrics Platform API docs.

Documentation metrics for MediaWiki

We've made great progress on this project over the past few weeks. We've defined metrics criteria and outcomes, documented our metrics selection process, and shared them within the team for feedback. The result is a draft proposal of 8 documentation characteristics that are indicators for 4 metrics categories: Relevance, Usability, Accuracy, and Findability. Check out the design requirements, methodology, and analysis, v0 set of metrics and data to measure, and the updated project documentation. This resolves two out of three of our research tasks and allows up to move up our testing schedule and start measuring some docs!

Documentation tools and processes research

We finalized researched into documentation tools used on GitLab, reviewing 370 repositories and listed 484 documentation items in total (T371671). We've now moved on to researching documentation tools used on Gerrit (phab:T371672).

Season of Docs

We reached an exciting project milestone this week: All remaining MediaWiki documentation pages on Meta-Wiki have now been moved to mediawiki.org. This officially completes the project to migrate this content started in 2006! A huge shoutout to User:Network-charles for his excellent work on this project.

Catalog-a-thon for GLAM tools in Toolhub

We're excited to share that a member of our team will be leading a session working on GLAM tools at WikiConf North America 2024. We've started planning for the session and meeting with subject matter expert to discuss feasibility of using Toolhunt during the event.

Docs outreach and support

We've continued work on plans for some new outreach activities for documentation support (phab:T371674). We also helped with some wrap-up tasks for the Coolest Tool Awards, including updating Wikidata entries for winners (query).

APaskulin (WMF) (talk) 23:54, 13 September 2024 (UTC)

Tech Docs update September 30, 2024

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.

Metrics Platform documentation

This project is shifting to focus on support for the Metrics Platform dashboard tool (MPIC). We've completed a proposed information architecture (T372690) to meet this goal, as well as worked on how to integrate the docs with the dashboard. We're continuing to work on reducing duplicating in the docs, and have made progress on a new measurement plan template.

Documentation metrics for MediaWiki

The first phase of the work is now complete! We've decided on and defined a set of v0 proposed metrics, including mapping available and unavailable data sources. Next quarter, we'll be continuing this work as we explore implementing these proposed metrics with sample doc collections.

Documentation tools and processes research

For this project, we continued the review of documentation tools used on Gerrit, currently at 178 repositories and 317 documentation items.

Catalog-a-thon for GLAM tools in Toolhub

We've completed preparations for this week's session working on GLAM tools at WikiConf North America 2024. Check out the program schedule to find us at the conference!

Docs outreach and support

We've finalized the plan for outreach initiatives for this year, and updated the parent task (T371674) with next steps and subtasks. We'll be starting with creating an IRC channel dedicated to providing tech docs support to communities (T375854).

Developer Portal

We completed our twice-yearly review of the site, including merging three patches to update content, upgrading the theme version, and publishing baseline metrics.

APaskulin (WMF) (talk) 00:12, 1 October 2024 (UTC)

Tech Docs update October 18, 2024

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.

Metrics Platform documentation

We've completed plans for moving forward on analytical sampling docs, rendering human-readable schemas, and the overall information architecture of the docs. We've split the API docs by language and completed initial updates. We also collected review feedback on the new measurement plan template and instrumentation spec template.

Documentation metrics for MediaWiki

The next phase of this project is focusing on testing a subset of draft metrics on an experimental group of technical documentation collections. We started by testing existing tools and looking at the aspects of documentation quality those tools enable us to measure. We used Quarry and PagePage to use the technical documentation dashboard to get specific sets of tech docs metrics for all pages within a given wiki category. For examples, see Documentation/Collections.

Documentation tools and processes research

We finalized the review of tools used on Gerrit, with 250 repositories and 477 documentation items included. We finished normalizing and cleaning up the research data and started the data analysis stage.

Catalog-a-thon for GLAM tools in Toolhub

The GLAM Toolhub edit-a-thon happened at WikiConf North America 2024! The session added a total of 275 new annotations to tool records in Toolhub. Thanks to everyone who contributed!

Docs outreach and support

We created the IRC channel dedicated to providing tech docs support to communities (T375854), including setting up the process and permissions. Join us in #wikimedia-techdocs ^connect channel on libera.chat! We also started work on the process for requesting documentation reviews and consultations (T375855).

Developer Portal

The theme upgrade for the site has now been completed and deployed.

GitLab documentation

We worked on improvements for the GitLab merge request documentation (T373122).

APaskulin (WMF) (talk) 23:31, 18 October 2024 (UTC)

Tech Docs update November 1, 2024

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.

Metrics Platform documentation

This project is now complete! We completed updates to the analytics sampling, custom schema, docs maintenance, and workflow guides, as well as submitting a patch to add docs links to the MPIC UI. You can check out the completed docs at wikitech:Metrics Platform and read the project summary on phab:T329506.

Documentation metrics for MediaWiki

At this point in the project, we're looking at sets of related docs (called collections) where we can test out the draft docs metrics and evaluate their usefulness. We've been looking at which MediaWiki collections to start on and gathering sets of page links. We chose the the MediaWiki REST API docs and completed a manual assessment, following the same method used for the ResourceLoader docs collection. Based on our experience with this manual assessment, we filed some tasks for the tech docs dashboard and learned more about how to use Quarry to get data about pages on mediawiki.org.

Documentation tools and processes research

This project is in its final stage. We completed the analysis of the data and have prepared a report to publish on wiki. The report in being reviewed by the team, and we hope to share it publicly next week.

Requestctl documentation

This project is now complete! This was a project in collaboration with WMF SRE to improve the docs for Requestctl, a tool used by SRE to respond to DDoS attacks. Quality documentation is essential to effective incident response, so we worked with SRE to design a task-focused guide and tutorials. Check out the docs at wikitech:requestctl.

Developer satisfaction survey

Tech Docs is participating in the Wikimedia developer satisfaction survey for the second year. We drafted the set of tech docs questions for this year survey and are working with the survey team to provide feedback.

APaskulin (WMF) (talk) 20:00, 1 November 2024 (UTC)

Tech Docs update November 15, 2024

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.

Documentation tools and processes research

This project is now complete! We finalized the analysis and published the final report. Check out the results and recommendations at Wikimedia Technical Documentation Team/Documentation tool study.

Replace jsduck with JSDoc3 across all Wikimedia code bases

This project is now complete! We resolved the two last codebases that needed to migrate, officially wrapping up the project. Aside from a few outliers and cleanup tasks that we'll be tracking separately, all codebases that were publishing JSDuck sites to doc.wikimedia.org have been migrated to JSDoc. For more details and a big thanks to everyone who contributed, see phab:T138401#10315025.

Documentation metrics for MediaWiki

We're moving forward with identifying test collections and experimenting with different metrics. We finalized the set of MediaWiki doc collections to test, and implemented them as PagePiles (T374722). We then started manual doc collection analysis to test proposed metrics, working on creating a standardized rubric to try to make the manual data gathering as consistent and easy as possible (T379431).

Season of Docs

This year's Google Season of Docs project is now complete! A huge shoutout to the technical writer we worked with this year, @Network-charles, for all his awesome work. Check out his final project report. To wrap up this project, we started work on a case study to submit to Google and documentation for the process of administrating the program.

Documentation metrics dashboard

We increased the page limit to 230, so you can now use the dashboard to analyze larger page piles.

APaskulin (WMF) (talk) 00:14, 16 November 2024 (UTC)