Season of Docs 2021 Information
Welcome to the ideas page for the PyMC3 entry in the 2021 Season of Docs. This page aggregates information regarding PyMC3's proposal, to give candidate writers an idea of what we are looking for to improve our project's documentation this year.
The core of PyMC3's documentation is comprised mainly of examples and tutorials in the form of Jupyter notebooks. Most of these are of high quality and have been useful resources for the library's user base, but they were created in isolation and essentially function in isolation, grouped together by topic in an ad hoc fashion. Moreover, because they were written by a different authors, often with different goals and emphasis, the amount and style of supporting text varies greatly among them. The goal of this project would be to sensibly and effectively integrate the existing documentation into a more focused, cohesive system. The resulting updates would better enable users to teach themselves Bayesian computation, and in particular, how to do Bayesian computation using PyMC3.
The Divio documentation system breaks down software documentation into four distinct quadrants:
- tutorials
- how-to guides
- explanation
- reference
Due in part to its origins described above, PyMC3's documentation is stronger on the right-hand side of this diagram than on the left. If a user has a well-defined, one-off task to complete, chances are they can find an adequate reference for implementing it among the project's collection of notebooks. For example, if you want to fit a latent variable Gaussian process there is a high-quality, runnable notebook that can act as a template for your own analysis. However, if you have dataset that might be well-served by using a latent-variable Gaussian process to model for inference, but you don't know about Gaussian processes you may miss it, and perhaps end up using an inappropriate type of model in its absence. Thus, there is an element of learning and understanding that needs to take place in order to make sound decisions regarding your analysis.
Most documentation includes an API reference as the only insight
- walk-through of computational backend
- important given the significant changes to PyMC3 computational backend
- developer-orientated
- most of our software documentation exists as ad hoc tutorials and howtos in the form of isolated Jupyter notebooks.
- no "syllabus" for new user to learn about how to use PyMC in a stepwise fashion
- navigation sidebar
- move documentation out of Wiki
- separation of library docs and project docs:
- library: about the software itself; tutorials, reference materials, etc.
- project: governance, community, etc.
The best way to contact the PyMC3 development team is via the project Discourse site.