Season of Docs 2022 Organization Application - sympy/sympy GitHub Wiki

NOTE: We are not currently accepting applications for this project.

Improving SymPy's Solvers Documentation

About your organization

SymPy is a Python library for symbolic mathematics. It was started in 2005, and has grown into a full-featured computer algebra system (CAS), which is used by people from a wide variety of domains, including education, finance, engineering, and science. As a symbolic mathematics system, it is applicable to virtually every field of science. SymPy is used by 30,000 Github repositories, has 8.7k GitHub stars and 3.5k forks, and is cited by more than 120 academic papers per year. SymPy also has a large contributor base. More than 1000 people have contributed to the project in its history. The contributors include hobbyists, people working in industry, academics, and students.

About your project

Your project’s problem

Solving mathematical problems is a top interest of the SymPy community, and the existing documentation for them lacks basic information on that topic. According to the Google Search Console, for Google search terms that lead searchers to our documentation site, the second most popular term is “sympy solve”, exceeded by only “sympy”. In a survey of the SymPy community, “solvers” was tied for the most popular response to “what areas of SymPy do you feel are not documented well enough?"

Currently, the vast majority of Google searches for “sympy solve” lead visitors to the API reference page for solvers. This page is very technical and long, and provides little high-level guidance on how to solve various types of math problems. Further, while “solvers” has the specific meaning in SymPy of “find the roots of an equation”, searchers may use “solve” to intend something more broad like finding the result of an integral or something else.

Further, the SymPy documentation has few examples of how to programmatically extract information from results. A developer who uses SymPy in code for their project will typically want to know how to extract the results of interest. For example, if a developer’s program solves a set of inequalities to obtain (1/2 < x) & (x < 7/10), the developer will likely want to extract 1/2 and 7/10.

It is important for SymPy to address this deficiency because many visitors are likely unable to quickly learn how to use SymPy to solve their math problems. This can lead to users giving up on SymPy or having to post for help on StackOverflow or SymPy’s mailing list. Those questions are often repeated with variations by different users. At best, the questions get answered by core developers at the cost of time that could have been spent improving SymPy. At worst, the questions may not get answered.

Your project’s scope

We will create a wide-ranging guide to solving for SymPy users. The main page will help direct users to the type of solving they need, whether it be one of SymPy’s solvers or “solving” an integral, etc. Initially, the main page will link to the most relevant existing content on the SymPy documentation site, for example an anchor on a page which demonstrates a given type of solving.

We will create a list of the types of solving needed. We will initially draft a list, then crowdsource additional types from the SymPy community via its active forums such as the mailing list and GitHub site. We will prioritize the types based on estimated usage, informed by Google Search Console search terms. The types will be sorted into priority categories (high, medium, and low), then a sub-page will be created for a given type, starting with the highest-priority types.

The sub-pages will contain step-by-step guides for how to solve each type of problem. The initial example for each problem type will be as mathematically simple as possible to ensure that as many users as possible understand the problem and solution. Further, the sub-page will demonstrate how to programmatically extract information from the results.

To help users find specific sub-pages using a search engine, each page will be optimized for SEO. For example, popular search terms include

python solve equation
sympy solve system of equations
sympy nsolve (nsolve is a SymPy module)

so the sub-page titles will follow a format like "Numerically solve a system of equations using SymPy nsolve".

Work that is out-of-scope for this project

It will be out of scope for this project to implement new types of solving or fix any bugs discovered. Instead, the technical writer will create GitHub issues for others to code improvements.

Time estimate

We estimate that this project will take approximately 300 hours.

Personnel

The SymPy community has identified Jeremy Monat as the technical writer. Jeremy has contributed code four times to SymPy, all related to documentation, using Sphinx, reStructured Text, docstrings, and doctests. He led the selection of a new Sphinx documentation theme which will make all pages on the documentation site more useful. He has also documented another Python project using Sphinx, reStructured Text, and Markdown, all of which the SymPy documentation uses.

Aaron Meurer will serve as the primary mentor for the project. Aaron is a lead developer on SymPy who has worked on the project for over a decade, and has served as the mentor for the Season of Docs technical writers for the past three years. He is currently funded 0.5 FTE (full-time equivalent) by the Chan-Zuckerberg Initiative to update SymPy API documentation. However, Aaron’s work will focus on different parts of the SymPy and will not conflict with this proposal.

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? In terms of helping SymPy users get to an easy-to-navigate page for solving, using Google Search Console we will measure the percent of searches for “sympy solve” which

return the new solving page as the first result
lead to the searcher clicking on the new solving page instead of another page on SymPy.

We will also ask the SymPy community to provide feedback on the new solving page.

In terms of content, we will track the number of sub-pages created from the list of the types of solving needed based on priority. Note: Because the SymPy community has opted not to have direct analytics installed on its documentation site due to user privacy concerns, we cannot track which page a user goes to next after a search leads them to a page on our site. Thus, we use more indirect analytics like Google Search Console.

Timeline

How long do you estimate this work will take? Are you able to breakdown the tech writer tasks by month/week? We estimate the work will take about 10 hours per week for the 30 weeks of the Season of Docs, or about 300 hours total. Here are the technical writer goals by month:

Month	Solving types	Main page	Sub-pages
April	Draft a list of solving types
May	Crowdsource from the SymPy community additional solving types	Develop and publish main page with the draft list of types of solving, linking to the most relevant existing content on the SymPy documentation site
June	Finalize and prioritize list of solving types	Request community feedback on the published main page	Develop and publish a first sub-page for 1 type of solving. Get feedback from the community.
July		Incorporate feedback into the main page	Develop and publish sub-pages for 4 types of solving
August			Develop and publish sub-pages for 4 types of solving
September			Develop and publish sub-pages for 4 types of solving
October			Develop and publish sub-pages for 2 types of solving

Project budget

General guidelines

Our budget is straightforward:

Budget item	Amount	Running Total	Notes/justifications
Technical writer develops user-facing solving page and sub-pages.	15000.00	15000.00

TOTAL: 15000.00

Additional information

The mentor Aaron Meurer mentored the prior Season of Docs technical writers for SymPy, and has worked with technical writers in a professional setting as part of his work as a software engineer. SymPy has participated in Season of Docs in 2019-2021 for a total of four projects. The reports for these projects can be found at