Skip to content

Season of Docs 2021 Information

Jump to bottom
Michael Osthege edited this page Mar 6, 2021 · 14 revisions

This page aggregates information regarding PyMC3's proposal for Google's Season of Docs 2021.

Ideas

  • Update and extend governance doc. It looks like the governance doc is outdated, and I think it needs to be extended in order to include the procedures to be followed for new contributors to join the project for example. (Oriol)
  • making sure the docs cover all areas in the image below and it is relatively clear which parts of the doc relate to which part. (Oriol)

source: https://documentation.divio.com/

(Oriol) I personally think that we are lacking on the explanation side, things like an architecture doc like it was proposed in slack (not sure if it was Brandon or Luciano) would be great resources, and I think they would mostly benefit devs, especially now with the v4 updates.

  • a sidebar, there are many themes like the rtd ones or the pydata (if we want to keep using a bootstrap based theme) that add a sidebar automatically, chaning from conf.py is easy, we'd just have to choose the new theme

Introductory Course Materials for New Users

(Michael) We have two places with notebooks: Examples and Gallery. I'm often confused by myself and have to look in both places when I'm looking for a specific notebook. I think we should merge the two.

Move Documentation away from Sphinx

(Michael) I don't think moving away from Sphinx should be a goal. Sphinx vs. MkDocs is just a technicality in the docs backend. Theme, navigation and content are important instead.

Splitting library and project docs

(Oriol) I think it would be good to try to separate as much as possible the docs on the library from the docs on the project. The docs on the library should probably be mostly built with sphinx/mkdocs (notebooks, api, guides... should allow changing versions ideally), whereas the docs on the project don't have any requirement really, don't need to have multiple versions, should contain info about generic learning (books, resources...) that don't change depending on the pymc version, about project governance, about the community, how to support the project...

Side note: it could help easing the transition away from sphinx if we decide to go with that.

(Michael) We have a few project docs in the PyMC3 Github Uncyclo, which is also not great. But we should at least link them.

References for ideas:

Contact Us

The best way to contact the PyMC3 development team is via the project Discourse site.

Clone this wiki locally