Documentation/Technical communication goals
 | This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on any information on this page. For updated info see Wikimedia Technical Documentation Team. |
About technical communication on Wikimedia projects[edit]
Technical communicators provide essential services, which include improving processes, creating technical documentation for individuals working on our projects, interacting with technical collaborators and helping them to surface and share their stories, working with staff and community members to improve the overall clarity, consistency, and civility of their communications, and providing consultation and information for individuals who require a better understanding of the technical aspects of our projects.
In a mature technical organization, technical communicators exist as an âinteractive group that moves information through many parts of the organization, connecting groups together and making the right parties aware of the information they need.â[1]
Technical communicators facilitate the free flow of information between people and teams inside and outside of WMF, reduce confusion about processes, create consistency, prevent redundancy of efforts, help to scale and scope of support for technical collaborators and increase the overall quality of user experiences across all of their touchpoints with Wikimedia technical projects.
Technical communicators are responsible for improving the overall quality of technical documentation on MediaWiki and Wikitech projects. Technical Communications will work closely with technical collaborators at WMF to improve onboarding and documentation for advanced developers. Technical Communications will emphasize collaboration and engagement with the Wikimedia technical community to increase understanding of technical concepts and projects, improve engagement and onboarding for emerging technical collaborators, and to provide a consistent technical documentation content experience for all Wikimedia technical volunteers.
Purpose[edit]
- Document the year-to-year efforts to improve technical communication within the Wikimedia ecosystem, including technical documentation content strategy (process improvements, writing, tooling, resources, community building), technical storytelling, and as a point of contact for individuals within the information-seeking information about the technology employed on our projects.
- Recommend a strategy for technical communication and content that is sustainable and can be supported by through the efforts of the Wikimedia technical community
- Advocate for better technical documentation across Wikimedia projects.
Accomplishments[edit]
2018/2019 FY[edit]
- Strategic planning for Wikimedia Technical Documentation
- Technical Writing Special Interest Group established
- Updated and improved the Wikimedia style guide for technical documentation
- Specific technical documentation content collections were identified for evaluation and improvement:
- MediaWiki action API Technical Documentation
- Wikitech/Toolforge improvements
- Supported two rounds of outreachy internships focused on technical documentation improvements.
- Re-established the monthly Tech Talk program for developers and technical collaborators to share their learnings
- Create a quarterly Technical Community Newsletter to share news and information relevant to the Wikimedia technical community
- Surfaced and contributed technical stories from the community:
- Published stories on Wikimedia Foundation Blog
- Supported members of the technical community to publish stories on Phame and to their own blogs
- Wikimedia technical documentation presence at conferences, hack-a-thons, and write-a-thons with a primary focus on outreach to new collaborators
- Outreach to technical writers in the wider FOSS community
- Consultation and technical documentation and communication support provided to individuals and internal teams on Product and Technology. Ex: Wikimedia Design Style Guide, Who Reads Wikipedia, Research Website, WikiCite Annual Report
2019/2020 FY[edit]
- Launch a Wikimedia Technology specific blog for members of the technical community to share technical stories.
- Assumed responsibility for @mediawiki and @wikitech social media channels to share and promote stories and news from the Wikimedia Technical Community
- Participate in Google Season of the Docs and other outreach programs.
- Outcome 1: Created and curated resources to help members of the technical community create better technical documentation
- Outcome 2: Improved navigation of Wikimedia Cloud Services documentation through the creation of new navigation boxes and templates
- Consultation and technical documentation and communication support provided to individuals and internal teams on Technology. Ex: MediaWiki REST API docs, API Gateway, MediaWiki API integration tests
2020 calendar year[edit]
- Launched Tech Blog in March
- 69 Edited and published posts.
- Editorial process and workboard management
- Reorganized/revisioned PAWS documentation on Wikitech
- Created PAWS tutorials for Getting Started and Working with Pywikibot
- Deep dive into PAWS content -- listed/categorized example notebooks for making Database and API connections
- Worked on social media strategy for Wikimedia Tech and MediaWiki
- Managed 9 Tech Talks
- Project and product management for API Portal
- Initial effort on API Portal content
- Hooks project documentation
- Documented REST API on mediawiki.org
- Attended two conferences (WTD and API Specs)
- Worked on Architecture team docs
- 8 months of internal documentation office hours
- Successful Season of Docs project mentorship
- Launched Friends of the Docs and held 4 meetups
- Biweekly tech docs sync
Strategy[edit]
2020[edit]
Organizational
- Establish user research processes and feedback loops to help us understand our audiences better.
- Ensure projects are properly scoped before resources are committed; this includes the creation of supportive tools to help guide requests for technical documentation.
- Create materials to help WMF teams create and manage technical documentation.
- Through biweekly triage meetings, technical writers monitor and manage the documentation workboard in Phabricator to support the workflow of technical contributors.
- Establish baselines for metrics that demonstrate the impact of their work.
- Share their activities and advocate for their work as a model for the community of technical contributors.
Documentation
- Improve processes and tools for creating and improving documentation across projects, including style guide, templates, contribution flows, categories/tags/labels, and versioning.
- Advocate and support automated docs where possible.
- Develop a process to indicate issues with existing documentation, such as methods to indicate if docs are inaccurate, outdated, incomplete, or inconsistent.
- Develop a process for reviewing documentation asynchronously.
- To move towards documentation content collections that are well-defined and easy to recognize, define important or priority collections and audit for topic coverage. Make these projects (and areas for improvement) visible to the community alongside tools and methods to make impactful improvements.
Outreach
- Launch a âFriends of the Docsâ group to engage writers, reviewers, and other people interested in docs from across the Foundation and the movement.
- Participate in outreach programs, including Outreachy, Google Season of the Docs.
- Run doc sprints at hackathons and relevant conferences.
2021[edit]
- Reorganization of Documentation pages on mediawiki.org
- Team toolkit for documentation
- A document that explains the difference between doc repositories and what theyâre used for/an audit of these sites to determine what is currently where and why
- Audit of Pywikibot content collection
- Targeted PAWS tutorials for onwiki tasks for newcomers/small wiki toolkits (range of topics)
- Investigation into using content types for documentation on wiki
- OAuth doc and UI overhaul
- Proposal for Jupyter Notebook integration with MediaWiki
- UX improvements for PAWS
- Documentation page wizard
- Nicer theme and homepage for MediaWiki Doxygen
- Metrics reports and dashboard
- User page badges/physical stickers/branding
- Compile a community documentation wishlist
- [Ongoing] Socialize review processes: test, share, and support this to see if we can get folks using it
- [Ongoing] Continue to build resources and templates for documentarians
- [Ongoing] Identifying and auditing more content collections
See also[edit]
Documentation/Maturity model for MediaWiki technical documentation