Hi All!
I have spent some time in the last month working on a rewrite of PyMC3’s documentation. I think it is just about ready to go, but wanted to get feedback before merging it.
I am hosting the updated docs here.
Major changes:
- Search results are better, search UI is cleaner
- The case study notebooks now have a beautiful gallery
- Front page has less stuff on it
My own list of TODOs includes:
- The example on the front page is pseudo code. Do you have a better short snippet of PyMC3 that will actually run and is easy to understand?
- The “quickstart” guide could also use an update
- There are a few other pieces of content (comparison with stan/edward/emcee/pyro/etc, where to open issues/request features) that might go well in an FAQ
- A link to this forum should perhaps move to the front page. It would be helpful to know if you agree with that!
- I spent about three hours trying to change the ugly anchor links for page headers to proper link icons. It wasn’t a good use of my time, and I still don’t know how.
Happy to incorporate suggestions for the next few days, or you can make a pull request against the new-docs branch in github!
4 Likes
I like the new format, in particular the examples gallery 
Quick feedback, as I am on mobile. The header and the code (in the installation section) do not reflow properly on mobile (chrome and safari). It is not big deal though.
1 Like
Hey Colin,
The new site looks really clean, I like it. A couple of points of feedback:
-
I think it would be a good idea to add additional links in a “Next Steps” section after the “Usage Overview” in the “Quickstart”, to give newcomers a clear path to travel after seeing the initial example. A rotating set of the “Examples”, or some educational references like those listed on the Github page, or even just a direct link to the “Learn” page could be useful. Currently it gives a quick taste of what things are like, but it doesn’t provide a lot of guidance on where to go if you don’t quite know what you’re looking for.
-
The examples that are provided with PyMC3 are probably one of my favorite features that you folks have put together. An amazing way to improve the “Examples” page would be to categorize and sort them in some way, so that they are not presented in this impassive wall. One way to organize them could be to have it mirror the API section, splitting into continuous vs. discrete and then into the main featured priors in the model example, or by splitting into general umbrellas of problems, like GLMs vs. mixture vs. time series, etc, each with its own header. A clear way to split out the examples would go a long way towards showing people looking for guidance exactly how much there is to offer in what you have done.
2 Likes
Thanks, Max and Jack!
regarding point 1: totally agree that the “quickstart” could use a tidy up and a rewrite, but I am marking that “conveniently out of scope” for this pr 
regarding point 2: the docs currently have that sort of arrangement, and I really like it too. I’ll hack a bit and see if I can set up either a static set of categories, or an easy way of tagging examples so they auto-organize, perhaps with some radio button filters.
I am also looking at the mobile css layout a bit!
@mmargenot Spent a few days crushing out some javascript, growing as a person, and teaching myself some new colorful language. I think this looks a lot better:
https://colindcarroll.com/static/pymc3/nb_examples/index.html
The categories are in a json file that we will edit manually, and any notebooks not categorized will go in “Other”.
There are a few strangely formatted ones, because I am counting on notebooks having a title slide with an h1 title, but I hope those get fixed through PRs.
1 Like
That’s exactly along the lines of what I was thinking. It looks great!