Google Season of Docs 2023: Proposal
In this section, tell us about your organization or project in a few short paragraphs. What problem does your project solve? Who are your users and contributors? How long has your organization or project been in existence? Give some context to help us understand why funding your proposal would create a positive impact in open source and the world.
Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python.
- Matplotlib has a large gallery of examples (around 600 files) which are classified by topic. The gallery has grown organically throughout the last 20 years and has never undergone a major overhaul. As for every data visualization library, examples are critical for understanding and effectively using the code, especially for the big group of our users who don't use Matplotlib on a regular basis.
- From a user perspective, it is difficult to know where to look for specific examples, and one example could also be associated with multiple topics. This creates usability and discoverability problems for our documentation. This project proposes work around defining a better information architecture for the example gallery, and developing categories and tags to classify these examples.
- A secondary task is to audit the examples and flag content improvements such as simplifying or scaffolding an example, adding a missing example, removing redundant examples, combining duplicates, etc.
Tell us about what documentation your organization will create, update, or improve. If some work is deliberately not being done, include that information as well. Include a time estimate, and whether you have already identified organization volunteers and a technical writer to work with your project.
This project will:
- Audit the existing example gallery content and provide a high-level overview;
- Identify possible indices and classify examples to improve usability;
- Propose the tagging scheme for existing examples;
- Suggest potential missing content based on the observation of the above mentioned classification;
- Identify and mark entry points and learning paths for users navigating the documentation, focusing on discoverability.
Deliverables:
- Proposed tags for 70% of the examples (either as pull requests or in a spreadsheet)
- Guidelines for choosing tags for examples and for proposing new tags, added to the writing documentation section of the docs
- Stretch goal: Guidelines for writing examples based on results of the audit
Implementing the actual tags for each example (i.e. submitting pull requests with the necessary changes to the gallery) is a stretch goal, and the success of this project does not depend on the completion of this task. This implementation can be finalized by the Matplotlib team after the end of this project.
Work that is out of scope for this project:
- Creating new content pages for the examples galleries.
- Decrease in number of issues raised for topics covered in the documentation
- A concept for user-friendly content organization in the gallery is developed, and gallery examples are tagged and classified according to the indexing defined through this discovery process
- A report on potential improvements, reclassifications and consolidation of the examples in the galleries.
- A user feedback session on the proposed tagging scheme
- Improvements in click through rates for getting to examples, as measured by Google Analytics (if tags are implemented)
| Dates | Action items |
|---|---|
| May | Technical writer is hired |
| June-August | Work on information architecture, experiment with tags and categories |
| September | Draft PR with indexing guidelines |
| September-October | Auditing existing content for duplicates etc. |
| November | Finalization and case-study |
| Budget item | Amount | Running total | Notes |
|---|---|---|---|
| Technical writer | 10,000.00 | 10,000.00 | |
| TOTAL | 10,000.00 |
- Nice to have:
- Experience with information architecture, usability studies, knowledge management
- Indexing/cataloging experience, particularly w/ visual corpora (visualizations, art, photos, etc)
- Teaching experience, especially with developing scaffolded examples
- Experience using and teaching Matplotlib (especially for auditing the examples)
Encourage community members to sign up to help with specific tasks, for example:
- @melissawm: happy to mentor and review docs pull requests
- @story645: domain specific mentoring for cataloging and auditing - visualization/education
- @paniterka: mentoring for usability, happy to review PR
Technical writers interested in working on this project should send an email to matplotlib-gsod@googlegroups.com by April 14th. Please include links to your technical writing work or portfolio/résumé/CV. You can also join the #mpl-gsod room on gitter.
Formal applications for the position must include a statement of interest.
Must submit by APRIL 30, 2023 at 13:00 UTC Matplotlib has chosen its technical writer for GSoD 2023 - see the announcement here: https://discourse.matplotlib.org/t/gsod-writer-hired/23796
Timeline (from GSoD guide)
- February 15, 2023 at 18:00 UTC Organizations can begin submitting applications to Google
- March 24, 2023 at 18:00 UTC Deadline for organization applications
- March 31, 2023 at 18:00 UTC Google publishes the list of accepted organizations
- APRIL 30, 2023 at 13:00 UTC Deadline for technical writers to submit their Statements of Interest according to the Google template
- May 10, 2023 at 18:00 UTC Technical writer hiring deadline
- March 31, 2023 - November 13, 2023 Hired technical writers work on documentation projects with guidance from organizations
- November 6, 2023 - November 21, 2023 at 18:00 UTC Organization administrators submit their case study and final project evaluation