Page MenuHomePhabricator

GSoD Proposal: Improve documentation for Wikimedia’s technical documentarians and videographers
Open, Needs TriagePublic

Description

About me

Name: Pavithra Eswaramoorthy
MediaWiki user: Pavithraes
IRC (Freenode): pavithraes
Location: India
Time Zone: UTC+5:30
Typical working hours: 20:00 - 03:00 (07:30 - 14:30 PDT)

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.


Project

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.

Deliverables

  • T197006 - Improve documentation for Wikimedia’s documentarians:
  • 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 - Create an “Introduction to Phabricator” screencast.

Stretch Goal


Mentors

  • Sarah R. Rodlund
  • Srishti Sethi

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.


Discussion

This project is broadly divided into two phases:

  1. Improve the existing resources for Wikimedia's technical writers.
  2. Create useful templates for potential videographers.

1. 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:

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ó:

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 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.

2. 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", 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.


Tentative timeline

Community bonding period (7th - 25th August)

  • 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 (26th August - 1st 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 (2nd - 8th 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 (9th - 15th 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 (16th - 22nd September)

Week 5 (30th September - 6th October)

  • Improve documentation for on-boarding new collaborators:
  • 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.


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.


Past Contributions


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 favourable 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)

Event Timeline

Pavithraes updated the task description. (Show Details)Jun 18 2019, 1:23 PM

@srishakatux @Quiddity @Aklapper
This is my first draft. I'd love some feedback on the feasibility of deliverables and the proposal in general. :)

This proposal looks wonderful. My only concern is that it seems to cover almost everything in GSOD leaving almost nothing for others! (semi-joking ;D ). However that might also mean that the scope is unfeasibly large? But your detailed timeline seems to indicate that you have good guesses about how long each action-item might take (and obviously some of that will change as you get deep into some tasks and need to adjust).

I think the item "Curate a list of tasks suitable for hackathons" might be the kind of thing that you update throughout the project, as you stumble upon new areas/aspects/details that need work. -- If you were planning to go through the list of (thousands of) Documentation tasks, I think the current method of denoting which tasks might be suitable is the combination of that tag and good first bug - here's a direct search for the overlap of those 2.

Regarding the "past initiatives" links, there are a few more in the "Notes" section at the bottom of my sandbox page here https://www.mediawiki.org/wiki/User:Quiddity_(WMF)/Hubs_and_docs

That's all I can think of for now. :)

Pavithraes added a comment.EditedJun 19 2019, 8:14 PM

@Quiddity Thank you for the feedback!

I'd selected the tasks considering GSoD spans ~4 months and no individual sub-project seemed to take that long. However, I do understand there would be unforeseeable delays, hence I'm labelling the last task - Wikiproject Screencast as a stretch goal. Do you still feel it is unfeasibly large?

You're right about "Curate a list of tasks suitable for hackathons" being an ongoing task throughout the project period, I shall make necessary changes to the proposal. :)
I was also thinking of organizing the hackathon tasks based upon the skill-set required and levels of difficulty. This might include tasks which aren't tagged as good-first-bugs, what are your thoughts?

Thanks for the links to past initiatives! I'll include a few. =D

Re: feasibility: If you feel confident, then it seems fine to me. (Or to use a military quote semi-humourously, "no plan of operations extends with any certainty beyond the first contact with the main hostile force" -source)

Re: "organizing the hackathon tasks based upon the skill-set required and levels of difficulty" - +1, sounds great! Any re-organization and expansion is welcome, as long as it remains easy for people to find tasks, and relatively easy to update/expand in the future. :-)

Pavithraes updated the task description. (Show Details)Jun 21 2019, 6:58 PM
Pavithraes updated the task description. (Show Details)Jun 21 2019, 7:06 PM

@Pavithraes Wonderful proposal! :) Here are a few comments:

  • +1 to Quiddity's comment on Hackathons tasks.
  • What use case will you be focusing on more for templates/user-guides for the video (software features, tool, technical implementation, a running program, etc. )? It's okay if you are considering to develop one that caters all use cases, but it would be nice if you could indicate that in the proposal.
  • You've mentioned that "in the end, there will be a hub..". Are you considering to work on the hub as well as part of your proposal? If you think there is some room still in the timeline, it would be nice to have this there as well and in the Deliverables section. I imagine a landing page for all the resources you might end up developing somewhere on MediaWiki.org.
  • About the Phabricator screenshot, check with Andre. I see that there are a bunch of related tasks he has assigned to himself and may have plans of working on some of them.
  • I see that your semester is overlapping with this program. That shouldn't be a problem, but make sure you have read all the program rules: https://developers.google.com/season-of-docs/terms/program-rules. I am also not quite sure what works, as we are doing this the first time :-/
Pavithraes updated the task description. (Show Details)Jun 22 2019, 4:31 PM

@srishakatux Thank you!
I've made the following changes based on your comments:

  • Mentioned the types of screencast templates and their use cases. (Deliverables, Timeline: Week 6)
  • Added the task of creating a technical writer's hub. (Deliverables, Timeline: Week 5)
  • Updated the proposal regarding hackathon tasks. (Timeline: Week 5)

I've re-read all the program rules thoroughly, and I shall let you know when the Phabricator screencast gets confirmed. :)

Pavithraes renamed this task from GSoD Proposal: Improve documentation for Wikimedia’s technical documentarians and videographers. to GSoD Proposal: Improve documentation for Wikimedia’s technical documentarians and videographers.Jun 27 2019, 9:45 PM
Pavithraes updated the task description. (Show Details)
Pavithraes updated the task description. (Show Details)Aug 24 2019, 3:39 PM