Talk:Wikimedia Technical Documentation Team
Welcome!
editHi, 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
editHi 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.
Tech Docs update June 30, 2023
editHi 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.
Tech Docs update July 14, 2023
editHi 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.
Tech Docs update July 28, 2023
editHi 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.
Tech Docs update August 14, 2023
editHappy 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.
Tech Docs update August 29, 2023
editHi 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.
Tech Docs update September 15, 2023
editHi 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.
Tech Docs update October 2, 2023
editHappy 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.
Tech Docs update October 17, 2023
editHi 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
editHi 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.
Tech Docs update November 20, 2023
editHi 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.
Tech Docs update December 11, 2023
editHi 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.
Tech Docs update December 21, 2023
editHi 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.
Tech Docs update January 25, 2024
editHi 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.
Tech Docs update February 10, 2024
editHi 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.
Tech Docs update March 1, 2024
editHi 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.
Tech Docs update March 22, 2024
editHi 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).
Tech Docs update April 12, 2024
editHi 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).
Tech Docs update April 26, 2024
editHi 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.
Tech Docs update May 17, 2024
editHi 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.
Tech Docs update June 7, 2024
editHi 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.
Tech Docs update July 3, 2024
editHi 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.
Tech Docs update July 17, 2024
editHi 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.
Tech Docs update August 1, 2024
editHi 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.
Tech Docs update August 21, 2024
editHi 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.