Season of Docs 2021 Organization Application - sympy/sympy GitHub Wiki
Google Season of Docs 2021 Organization Application
Documentation Organization - SymPy
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 also has a large contributor base. Over 1000 people have contributed to the project in its history. The contributors range from hobbyists, people working in industry, academics, and students.
About your project
Your project’s problem
SymPy is itself a large project. The library has over a thousand public functions and methods, and consists of over 700k lines of code. About a third of these lines of code (240k) are documentation in the form of docstrings, and there are an additional 32k lines of Restructured Text documentation outside of the library source code. The result is that SymPy has a lot of documentation. And there still remains a great deal of documentation that needs to be written, which will make the problem only worse.
The project is to improve the organization of SymPy's online documentation at https://docs.sympy.org/. Right now, it can be difficult for users to find what they want because sheer quantity of documentation. There is also not a clear delineation of the different types of documentation, meaning that things like tutorials, API documentation, and user guides are sometimes intermixed.
Your project’s scope
The project will consist of developing and implementing a new organization for the SymPy documentation, as well as developing any guides or processes necessary to ensure the documentation stays organized in the future. We would suggest using the Diátaxis documentation system (https://diataxis.fr/) as a starting point for the organization, although we are open to other organization ideas if a technical writer wishes to propose one.
The first stage of the project will be to do an audit of SymPy's existing documentation, so we can have a better idea of what is there. This will include looking for documentation that is in the "wrong place", such as documentation that is currently in API documentation (docstrings) that may not belong there. It should also include taking stock of documentation that is not yet written but may be written in the future, so that the organization plan can include those when they are written. For example, SymPy currently does not have very many user guides that are independent of API documentation, but we want to write more. This will also help us to identify gaps in our current documentation.
The next stage will be to develop a plan for how the documentation will be organized. This will include developing some method(s) on getting user feedback, so that we can be sure that the organization plan is able to help users best find what they are looking for. This will include SymPy user survey on documentation, which will also be used to measure the project's success (see the next section). Other prudent methods of user feedback may be suggested by the technical writer. The documentation organization plan should include a new section in SymPy's documentation style guide about the organization, so that contributors of new documentation can properly maintain the organization.
The final stage will be to adopt the new organization and make the SymPy documentation site follow the new organization. This will require technical knowledge of the RestructuredText (RST) and Sphinx documentation system that SymPy uses. Depending on how different the new organization plan is from the existing documentation, this may need to be implemented in several stages, to minimize the disruption to the rest of the SymPy development.
Work that is out-of-scope for this project:
It will be out of scope for this project to write new documentation for SymPy that is found to be missing. New documentation requires technical knowledge of SymPy and the underlying mathematics and generally must be done by an existing SymPy developer with the proper domain knowledge. Instead, the technical writer should make note of any gaps in documentation, which the SymPy team can then use when writing documentation in the future.
Measuring your project’s success
We will develop a user survey to measure how well users are able to navigate the SymPy documentation. We will give this survey before and after the project. The questions on the survey will be designed in such a way that we can measure how the user experience has improved. We will consider the project to be a success if the end-project survey shows a marked improvement in usability compared to the pre-project survey.
Project budget
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer develop and implement new documentation organization for SymPy documentation. | 10000.00 | 10000.00 |
TOTAL: 10000.00
Additional information
Previous experience with technical writers or documentation
SymPy has participated in Google Season of Docs in 2019 and 2020. For a total of three projects. The reports for these projects can be found at
- GSoD 2019 Report Lauren Glattly: SymPy Documentation Style Guide
- GSoD 2020 Report Soumi Bardhan: Consistency across docstrings - SymPy Documentation
- GSoD 2020 Report Rohit Goswami: SymEngine
Additionally, the mentor Aaron Meurer has worked with technical writers in a professional setting as part of his work as a software engineer.
Previous participation in Season of Docs, Google Summer of Code or others
We have participated in Google Season of Docs in 2019 and 2020, for a total of three technical writer, and we have participated in Google Summer of Code every year since 2007, for a total of 85 successful projects (we are also participating in GSoC this year). This has given us significant experience in mentoring people who are new to the project. The past Google Season of Docs projects have also given us experience in working with a technical writer, and has helped us to understand the sorts of things that technical writers need more help onboarding with, and the sorts of ways that technical writers can be beneficial to the project.