Documentation Refresh

[jsignell]

Dask has a tremendous amount of well-written documentation, but I am not sure if it is presented effectively (if anyone has any insight on this I'd love to get some data about it). These are some ideas that I am thinking about:

• Fewer pages in the left-nav. I have been seeing other projects make a clearer split between For Users and For Developers/Contributors I feel like that's a tough split for Dask since there is so much overlap and lots of users end up extending or needing to know about the internals for some other reason. I think that these could be grouped into a page called Internals and a lot of the pages that are in Help and Reference and Diagnostics could be moved into that section.
• Include the new figures from Updated figures #135 and make them clickable.
• Use top nav section more effectively. Since that piece is consistent across subprojects, it should consistently point to the most globally useful places.
• Use the right space better. The xarray docs put page level TOC at the right of the page. That feels like a nice improvement to me.
• Make one API Reference rather than separating out Array, Dataframe ... right now there is a lot of duplication between https://docs.dask.org/en/latest/dataframe-api.html#create-dataframes and https://docs.dask.org/en/latest/dataframe-create.html
• Not to pick on dask.dataframe too much, but this TOC is really hard to navigate
  I think it could be improved by removing the section headers from the TOC or somehow moving them up.

I am particularly motivated by the xarray doc refresh. I think their theme looks very nice as well, but I'll save that for another time...

Current docs

Xarray

[jacobtomlinson]

Thanks for starting this thread @jsignell. I'm definitely keen to improve the docs and help here in whatever way I can.

In my experience with things like refactoring docs you need to build a map of the whole thing in your head, or have multiple people involved who can act at stakeholders for each section. Then try and draw out a new map which includes all of the content.

I wonder if it would be worth spending half a day on Whereby hashing it out?

[jacobtomlinson]

if anyone has any insight on this I'd love to get some data about it

It looks like the docs has good analytics (at least for the primary docs site). This would be a good source of data. @mrocklin can we get access to this more widely?

Include the new figures from Updated figures #135 and make them clickable.

There was a discussion a while back in Coiled funding a Sphinx developer to work with the designer that did the branding refresh to build a new docs theme. Has that conversation gone any further @mrocklin @jrbourbeau?

[jsignell]

In my experience with things like refactoring docs you need to build a map of the whole thing in your head, or have multiple people involved who can act at stakeholders for each section. Then try and draw out a new map which includes all of the content.

Yes yes yes. In case you can't tell from this rambling issue that is what I tried to do yesterday 🙄 with limited sucess....So I figured the time had come to just open the issue.

I wonder if it would be worth spending half a day on Whereby hashing it out?

This sounds like a really good idea to me. I think a group of 2-4 people would probably be able to do a good job of it. In that amount of time.

[michelechambers]

if anyone has any insight on this I'd love to get some data about it

It looks like the docs has good analytics (at least for the primary docs site). This would be a good source of data. @mrocklin can we get access to this more widely?

Include the new figures from Updated figures #135 and make them clickable.

There was a discussion a while back in Coiled funding a Sphinx developer to work with the designer that did the branding refresh to build a new docs theme. Has that conversation gone any further @mrocklin @jrbourbeau?

We didn't find a Sphinx developer so that hasn't moved forward. If anyone knows a good Sphinx developer, let me know and I'll follow up.

[mrocklin]

if anyone has any insight on this I'd love to get some data about it

It looks like the docs has good analytics (at least for the primary docs site). This would be a good source of data. @mrocklin can we get access to this more widely?

I've added @jacobtomlinson and @jsignell to the Google Analytics page.

I'm inclined to add @michelechambers as well if people are comfortable with that. For context, Michele works with Coiled. She managed Anaconda's marketing for a long while. I think that having her insight here would be helpful. I'd like some Coiled-exernal validation of that though before granting permissions.

[mrocklin]

I wonder if it would be worth spending half a day on Whereby hashing it out?

This sounds like a really good idea to me. I think a group of 2-4 people would probably be able to do a good job of it. In that amount of time.

I agree that we probably don't want this group to be too large. Redesigning docs is like a giant shed full of bikes. I also think that it would be useful to collect some information asynchronously ahead of time.

<nerd snipe> would anyone be interesting in looking at 10-20 documentation pages for different projects, collecting screenshots, writing down some notes on trends, and then then sharing that information with the group? I think that some prepartory activity like this might help to elevate the level of conversation. I also think that it would make for a fantastic blog post </nerd snipe>

[jsignell]

Oooh I like that idea. I would be happy to take a look at some different projects' docs.

[mrocklin]

We didn't find a Sphinx developer so that hasn't moved forward. If anyone knows a good Sphinx developer, let me know and I'll follow up.

@michelechambers also, as a heads up, we do actually have an offer out here on the engineering side.

[jsignell]

Ok here's my list for the docs survey. I probably won't get to them all, but let me know if you think there are others that might be interesting:

• xarray
• numpy
• pandas
• cudf
• R - dplyr
• R - data.table
• tensorflow
• pytorch
• streamlit
• django
• matplotlib
• bokeh
• spark
• prefect
• jupyter

[phaustin]

z2jh is having a related discussion: jupyterhub/zero-to-jupyterhub-k8s#2313

[jsignell]

Thank you so much for mentioning that! I just watched the video and I feel pretty persuaded :)

[jacobtomlinson]

I just wanted to surface the DjangoCon talk from the z2jh issue which is being discussed. I found it an excellent watch and have a lot of things to think about.