The Wikimedia Foundation project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
The Wikimedia Foundation
Technical writer:
Pavithra Eswaramoorthy
Project name:
Improving documentation for Wikimedia’s technical documentarians and videographers
Project length:
Standard length (3 months)

Project description

1. About me

I was introduced to open source software a few months back and almost immediately felt overwhelmed by its limitless scope. Struggling to make my way through the bazillion projects, I learnt about open source initiatives like Google Summer of Code and Outreachy. Google Season of Docs seemed interesting and the project ideas by The Wikimedia Foundation piqued my curiosity, so, I began exploring further.

My journey so far has been equal bits of exciting and confusing, filled with “Wait, what?”, “Ahh, I get it!” and “Should I comment on this?”. The Wikimedia community has been supportive at every step. From editing pages to creating extensions, I’ve learnt something new every day.

As expected, the application process served as my gateway into the open source community. This proposal is inspired by my own experiences as a beginner.

2. Project

2.1. Outline

This project aims to improve documentation for technical writers and potential videographers across Wikimedia. A mature set of technical documentation guidelines would help foster improved overall documentation, and references for creating screencasts would enable demonstration of software features effectively. The existing documentation in these areas can be extended to better support both newcomers and seasoned contributors. An incremental approach will be adopted to develop this network of handy resources.

2.2. Deliverables

  • T197006 [https://phabricator.wikimedia.org/T197006] - Improve documentation for Wikimedia’s documentarians:

    • Add tips and examples to Documentation/Style guide. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Add MediaWiki specific information to certain genres in Technical documentation templates and suggestions: User guides, how-to’s, quick-start-guides, release notes and READMEs. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Test and Improve the guidelines for Technical documentation prioritization. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Design a content collection strategy for different genres of documentation.
    • Design a communication and collaboration strategy for MediaWiki’s documentation.
    • Create a checklist against which writers can review their docs before publishing.
    • Expand the documentation structure for new technical writers. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Curate a list of technical documentation tasks suitable for hackathons. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Create a technical writer’s hub that points to useful resources.

  • Improve documentation for MediaWiki's videographers:

    • Create a quick-user-guide for making a general screencast.
    • Design MediaWiki-specific screencast templates for walkthroughs and tutorials.

  • T214522 [https://phabricator.wikimedia.org/T214522]- Create an “Introduction to Phabricator” screencast.

2.3. Stretch Goal

  • Re-check the content and update WikiProject Screencast documentation. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentors

Zulip will be the primary mode of communication with my mentors. Wikimedia’s IRC channels and Email will be used for discussions with the community. Discussions about specific tasks will happen in the comments section of the Phabricator tasks.

4. Discussion

This project is broadly divided into two phases:

(i) Improve the existing resources for Wikimedia's technical writers.

(ii) Create useful templates for potential videographers.

(i) Improve the existing resources for Wikimedia’s technical writers.

In the past, there have been several initiatives to improve MediaWiki’s documentation with varying degrees of success. To name a few:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

From these efforts, we can understand that a better set of resources for technical writers will have a direct impact on the documents generated by them.

The following is a snippet from the bi-weekly report of an Outreachy 2018 intern, Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

“MediaWiki’s style guide is far from being perfect, especially as it relies too much on external references without highlighting which practices it considers the best. Unfortunately, this is a problem that is not confined solely to MediaWiki, as it shows up on other documentation like the Translation best practices. Writers end up without good and reliable resources to do their work, leading to difficulty in establishing a target audience and a proper style of writing. And users, especially new users, may face problems to understand new concepts and processes.”

T197006 [https://phabricator.wikimedia.org/T197006] also sheds light on certain areas of technical writing documentation that need improvement. Clearly, Documentation/Style_guide is the place to begin.

Once we have a better style guide, the next set of docs are planned to guide technical writers through the different stages of technical writing. The docs need to be beginner friendly and at the same time provide all necessary information for writers to refer back to.

The preparation stage is possibly the most important as it lays the foundation on which the document is built. To support technical writers through this stage, reference docs are developed describing some effective ways to gather relevant information and tips on structuring this information using templates.

Then comes the writing stage. Writers are provided with examples of good work to automatically set the bar high. Furthermore, a checklist is created with a set of basic criteria every doc must follow, this will assist writers in reviewing their docs before publishing.

Even with these documents, new technical writers will need extra help, and we need to give it to them. The guide for new technical writers is refined and a list of tasks suitable for hackathons is curated based on the level of difficulty.

Finally, a document to understand the process of managing and maintaining documentation - 'Technical documentation prioritization' is tested and improved.

At the end of this phase, a hub of technical writing guides, resources, examples, suggestions and templates will be established supporting the documentation style guide.

(ii) Create useful templates for potential videographers.

“One of the hardest ways to learn anything that involves graphics is by reading plain text. Imagine also what happens if your manual refers to the wrong version of the software - with text-only manuals it often becomes impossible to recreate a series of actions when the menus and wording in the application changes as we lack all the cues we'd normally use.

Perhaps the best way to learn is when you have an expert sat right down beside you. Screencasts sit between static graphics and having an expert close at hand. We get a visual, moving demo with a friendly voice, we can also have text annotations on screen and animations. An advantage of screencasts over an expert is that they can be replayed at will every hour of every day.

We can also add translated subtitles to a screencast so they can be viewed by non-native speakers or replace the audio track with alternate languages.“

In the above snippet from ""The Screencasting Handbook"" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald explains the significance of screencasts. It could be especially useful for tutorials on setting up the MediaWiki development environment, writing extensions, using Gerrit, and more.

Similar to templates for documents, having a standard template for screencasts promotes uniformity, thereby improving the viewer’s experience. It also provides potential videographers with a framework to get started. Hence, a quick-user-guide followed by templates for creating introductory and tutorial videos is developed. The docs include pointers about the depth of concepts to be covered and a few screencast ideas for MediaWiki.

The best way to test the above template and prepare for the stretch goal is to create a screencast using the tools and templates. Hence, an “Introduction to Phabricator” screencast that covers the basics of using Phabricator is created. This process would also highlight the areas that need discussion.

Finally, the central source of reference for Wikimedia’s videographers - WikiProject Screencast is reviewed and updated.

5. Tentative timeline

Community bonding period (1st August - 1st September)

  • Analyze the project in detail with my mentors.

  • Discuss about:

    • How often the tasks should be reviewed.
    • Share schedules and decide on a weekly/daily workflow.
    • Tools and resources that can be used.
    • Bi-weekly and daily project reports.

  • Create the required tasks and subtasks on Phabricator.

  • Create drafts to compensate for personal commitments during the doc development phase.

Week 1 (2nd - 8th September)

  • Improve the Documentation/Style_guide:

    • Shift the primary focus to illustrate the best practices and standards on MediaWiki.
    • Include examples of good work and improve the visibility of associated pages.

  • Improve the guide for New technical writers:

    • Expand the documentation structure.

Week 2 (9th - 15th September)

  • Work on Technical documentation prioritization:

    • Assess the documentation workboard; find examples of good task descriptions and prioritization.
    • Study the trends and note down common difficulties.
    • Use the information and examples to document the prioritization standards.

Week 3 (16th - 22nd September)

  • Create the following additional documentation for technical writers:

    • A checklist to help review technical documentation before publishing.
    • Ways to collect content effectively for different documentation genres.

Week 4 (23rd - 29th September)

  • Add information about writing in the most common MediaWiki genres to Technical documentation templates and suggestions:

    • Document the best practices on MediaWiki for writing user guides, quick-start-guides, READMEs, release notes and how-tos.

  • Add directions to improve the maturity of technical communication. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Week 5 (30th September - 6th October)

  • Improve documentation for on-boarding new collaborators:

    • Update the page: Technical documentation tasks for hackathons. (To-do: Add suitable tasks to this page throughout the project period)

  • Build a technical writer’s hub

    • Create a landing page with links to useful pages and resources.
    • Add necessary links to the new and existing pages for easier navigation between them.

Week 6 (7th - 13th October)

  • Create the following documents on making videos for MediaWiki:

    • A quick-user-guide on 'creating a general screencast' pointing to the Screencast Project.
    • Templates for: Walkthroughs on using a software/tool; Tutorials on developing new tools.

  • Create a list of screencast ideas for MediaWiki.

Week 7 (14th- 20th October)

  • Work on the ""Introduction to Phabricator"" video:

    • Use the template (created the previous week) to draft a script.
    • Estimate the efficiency of the template and improve it if necessary.
    • Get feedback and finalize the draft.

Week 8 (21st - 27th October)

  • Publish the “Introduction to Phabricator” video:

    • Select and install the software.
    • Set up the environment and create the screencast.
    • Note down the issues encountered and solutions.

Week 9 (28th October - 3rd November)

  • Work to improve the Screencast project documentation:

    • Examine the structure and discuss any need for changes.
    • Review the softwares mentioned.
    • Research and update the list of softwares.

Week 10 (4th - 10th November)

  • Continue to improve the Screencast project documentation:

    • Evaluate and improve the tutorial and scripts.
    • Review the screencast gallery.

Week 11 (11th - 17th November)

  • Complete the work on Screencast project documentation:

    • Find and add newer videos to the gallery.
    • Make the necessary structural changes.

Week 12 (18th - 24th November)

  • Work on any pending tasks.

  • Write the final report:

    • Refer to the bi-weekly/daily reports and collect the required information.
    • Plan the report structure and write a draft.
    • Improve and finalize the draft based on mentor’s feedback.

Week 13 (25th - 29th November)

  • Submit the final report and mentor evaluation.

6. Progress Tracking

Daily progress updates will be communicated to my mentors over Zulip. The Wikimedia community can track my progress through Phabricator or the bi-weekly project reports.

7. Other Commitments

I am a full-time college student and my academic fall semester overlaps with the Season of Docs timeline. Hence, my commitments include college exams.

First internal exam: 18th to 24th of August

Second internal exam: 29th of September to 6th of October

End-semester exam: 11th to 30th of November

I also plan on attending my first public conference, PyCon India from 12th to 15th of October, thanks to the favorable location this year. I believe it would be a great opportunity to meet new people and have insightful conversations.

To manage these commitments, the tentative timeline contains less weighty tasks in the corresponding weeks. I intend to complete not more than 20 core credits in the fall semester to have sufficient time for doc development. (A regular student completes 25 credits on average per semester)