GSoD Proposal 2022 - NumPy

--- tags: numpy --- # GSoD Proposal 2022 - NumPy **Title**: Create and document user journey maps and personas for NumPy ## About your organization NumPy is widely used in almost every field of science and engineering. Over 32,000 packages on GitHub depend on NumPy, and 6 million users visit our website every month. Its user base spans from beginner coders to experienced researchers doing state-of-the-art scientific and industrial R&D. NumPy is the universal standard for working with numerical data in Python, and is at the core of the scientific Python and PyData ecosystems. It provides ndarray, a homogeneous n-dimensional array object, with methods to efficiently operate on it. SciPy, Matplotlib, scikit-learn, scikit-image, and most other data science and scientific Python packages use the NumPy API extensively. Deep learning frameworks (e.g., Tensorflow, PyTorch) and array computing libraries for other programming languages also replicate NumPy's API and strive to remain compatible with NumPy. ## About your project ### Your project’s problem Historically, NumPy was developed within SciPy. Although now independent, NumPy and SciPy are tightly linked communities. The decoupling of projects is relatively recent, and until some time ago, they shared one documentation and website. Both NumPy and SciPy have huge user bases, with people from many different backgrounds and experience levels. Both projects also have large documentation bodies, 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. It can be difficult to rank pages by importance, or prioritize what is necessary from what is optional. The scope of both projects are manifestly different: NumPy aims to provide a minimal set of efficient tooling and constructs which are able to support the rich ecosystem of dependent libraries (of which SciPy forms a part), while SciPy is a downstream consumer of the NumPy constructions. Its aims can be paraphrased into providing the Scientific Community with a trusted reference implementation of algorithms. Due to the strong coupling of NumPy and SciPy, this distinction can sometimes be hard for new users to understand (e.g. some search engines like DuckDuckGo still point to older copies of the NumPy documentation within SciPy). An introductory guide to the NumPy ecosystem would go a long way towards helping readers distinguish the differences between the two projects. In keeping with the Community directions of diversity and inclusion, the NumPy documentation team would like to quantify such a scope definining document in terms of specific user-stories and journey maps. This project aims to identify and document [user stories](https://en.wikipedia.org/wiki/User_story) and personas as well as [journey maps](https://en.wikipedia.org/wiki/User_journey) that represent common use cases for NumPy, identify pain points, and also link to relevant documentation which is out of scope for NumPy. ### 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 serves 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 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. We expect that the core focus for a concrete realization of the project will involve guided maps through the existing documentation, and as such, we do not foresee the need for more tutorials for end-users and downstream projects. We would like to select one technical writing candidate for this project, anticipating that if SciPy 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 NumPy is best. Technical writers interested in this project should have: - [ ] Basic understanding of Sphinx for documentation - [ ] Understanding of the NumPy project scope - [ ] The willingness to attend documentation team meetings and comply with NumPy review requirements - [ ] Basic knowledge of inclusive writing practices Two experienced mentors will be available to provide walkthroughs, and arrange times for discussions or interviews with end-users and content experts, as needed. We are open to listening to writers' suggestions and contributions. ### Measuring your project’s success The NumPy 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 NumPy; + 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. + We expect each persona to add roughly a page to the documentation - 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. + As we expect the technical writer to interview / survey portions of our user-base, the recommendations report will tie these into a narrative guideline which can be used as a reference for future documentation projets 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 NumPy | 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.* NumPy successfully participated in Google Season of Docs in 2019, 2020, and 2021. The mentors for this project are members of the NumPy community, with experience mentoring and creating documentation, as well as around the tooling and infrastructure involved in creating the documentation for NumPy. The mentors for this year, Melissa Mendonça and Ross Barnowski, also served as mentors for last year's Google Season of Docs. The NumPy documentation and development teams drive and decide on doc changes as they are proposed. We also welcome ideas around accessibility, usability and inclusion when creating documentation for NumPy. The Documentation Team holds bi-weekly meetings to openly discuss goals and projects with the NumPy community. Current documentation: - Latest version (tutorial, reference guide, developer docs): https://www.numpy.org/devdocs/index.html - Historical archive of released documentation: https://docs.scipy.org/doc/ - NumPy website: http://www.numpy.org/ - SciPy ecosystem website (which NumPy is at the core of): https://scipy.org/ - GitHub repository (all sources for code and docs): https://github.com/numpy/numpy - Jupyter Notebook repository (not integrated into the main documentation): https://github.com/numpy/numpy-tutorials ---