HackMDGSoD Proposal 2022 - SciPy
Title: Create and document user journey maps and personas for SciPy
About your organization
SciPy is a collection of mathematical algorithms and convenience functions built on the NumPy extension of Python. It adds significant power to the interactive Python session by providing the user with high-level commands and classes for manipulating and visualizing data, which makes it accessible and productive for programmers from any background or experience level. SciPy provides algorithms for optimization, integration, interpolation, eigenvalue problems, algebraic equations, differential equations, statistics and many other classes of problems.
About your project
Your project’s problem
Although now independent, SciPy and NumPy are tightly linked communities. Until some time ago, they shared one documentation and website, and there is considerable overlap between users and even contributors of both libraries.
Both NumPy and SciPy have a huge user base, with people from many different backgrounds and experience levels. Both projects also have a large documentation body, with extensive coverage of technical details, architecture and design decisions. Although comprehensive, the size and depth of the documentation for both projects can be a challenge for new users and new contributors, because it may be difficult to rank pages by importance or prioritize what is necessary from what is optional.
This project aims to identify and document user stories and personas as well as journey maps that represent a few common use cases for the NumPy and SciPy documentations, identify pain points and implement solutions to them with the help of both communities.
Your project’s scope
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.
NumPy and SciPy serve many kinds of users: students new to programming or Python, educators, researchers, domain experts in one of the areas that the projects cover, data scientists, library developers, packagers, and more. Our goal is to provide ways to guide those users to the parts of the documentation most relevant to them.
This project aims to:
- Identify typical user personas per project, and audit the current documentation for the workflows these personas face and their overall user experience in both sets of documentation;
- Reorganize the documentation for both projects to make those workflows clearer;
- Create minimum sets of documentation for these workflows;
- Work with the community to create journey maps for these personas and identify pain points and problems in the current organization of the docs;
- Suggest and implement changes to the documentation based on this research.
Work that is out-of-scope for this project:
- Creating tutorials for end-users.
We would like to select one technical writing candidate for this project, anticipating that if NumPy is also accepted into the program the technical writers selected for both projects can collaborate as the projects are similar. We have two mentors who have committed to supporting the project.
Although we anticipate some time will be spent on onboarding and learning the technical processes involved in working on our documentation, to be able to identify our users and the target audience for our documentation, some familiarity or previous experience with SciPy is best.
Technical writers interested in this project should have:
- Basic understanding of Sphinx for documentation
- Understanding of the SciPy project scope
- The willingness to attend community meetings
- Basic knowledge of inclusive writing practices
Two experienced mentors will be available to provide walkthroughs, set up time for discussing with or interviewing different kinds of end-users and content experts as needed. We are open to listening to writers' suggestions and contributions.
Measuring your project’s success
How will you know that your new documentation has helped solve your problem? What metrics will you use, and how will you track them?
The SciPy issue tracker shows a large number of documentation-related issues. Although it is possible that some of them will be solved in the course of this project, this is not our main focus.
We would consider the project successful if:
- Five user personas are identified and documented for SciPy;
- Each persona should be fleshed out to reflect the diversity in our user base, and also to support a wide variety of backgrounds and experience levels.
- User journey maps are documented for each of the personas identified;
- Each user journey will involve segments of the documentation along with a rough time commitment
- Each user journey will consist of a guided tour of relevant sections of the documentation in response to common questions
- A report with recommendations is created to guide the implementation of the changes suggested by this research.
If there is time and the writer is interested, they can implement high-priority tasks identified in the first part of the work.
Timeline
We anticipate the project to be developed over six months, and we expect the technical writer to be able to dedicate around 20 hours per week for the project. This timeline includes the onboarding of the technical writer and reviewing existing literature on user journeys and how to effectively identify different use cases for the documentation.
| Dates | Action Items |
|---|---|
| May | Onboarding and literature review |
| June - July | Audit existing documentation and identify user personas |
| August - September | Identify user journey maps |
| October | Write report and create recommendations for documentation improvement |
| November | Project completion |
Project budget
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer for SciPy | 15000.00 | 15000.00 | |
| TOTAL | 15000.00 |
Additional information
Include here any additional information that is relevant to your proposal.
- Previous experience with technical writers or documentation: If you or any of your mentors have worked with technical writers before, or have developed documentation, mention this in your application. Describe the documentation that you produced and the ways in which you worked with the technical writer. For example, describe any review processes that you used, or how the technical writer's skills were useful to your project. Explain how this previous experience may help you to work with a technical writer in Season of Docs.
- Previous participation in Season of Docs, Google Summer of Code or others: If you or any of your mentors have taken part in Google Summer of Code or a similar program, mention this in your application. Describe your achievements in that program. Explain how this experience may influence the way you work in Season of Docs.
SciPy has successfully participated in Google Season of Docs in 2019. The mentors for this project, Pamphile Roy and Melissa Mendonça, are members of the SciPy Community, with experience mentoring and creating documentation, as well as around the tooling and infrastructure involved in creating the documentation for SciPy.
The SciPy maintainers drive and decide on documentation changes as they are proposed. We also welcome ideas around accessibility, usability and inclusion when creating documentation for SciPy. We have bi-weekly community meetings and also plan on working closely with the NumPy documentation team.
Current documentation:
- Latest version (tutorial, reference guide, developer docs): https://scipy.github.io/devdocs/index.html
- Historical archive of released documentation: https://docs.scipy.org/doc/
- SciPy website: http://www.scipy.org/
- GitHub repository (all sources for code and docs): https://github.com/scipy/scipy
