What is still missing in the documentation?

[NoraLoose]

• Statement of need #37 Statement of need (on landing page, above table of contents; can be similar to what we write in the JOSS paper: First draft of JOSS Paper #76)
• Installation Instructions #39 Installation instructions
• What else?

Right now, we have a page with the Filter Theory and many tutorials.

• Do people feel that we need something in between, like a general introduction to how the package works, e.g., a mention of the core object gcm_filters.Filter?
• A lot of the important general concepts are covered in the Filter Theory and the first tutorial. So a second option is to leave the documentation as is (with potential small edits of the Filter Theory and the first tutorial), since folks prefer to learn with examples anyway.

Thoughts? The more opinions, the better.

[rabernat]

Thanks so much for continuing to work on this Nora! It's really coming together. I agree we should make some tweaks to the documentation organization.

Regarding installation, I have just released v0.1 pypi, which means you can just pip install gcm-faces. We should feel free to keep making new releases as often as we want when new features com online.

• Do people feel that we need something in between,

YES. I think we would benefit what is called "narrative documentation", which explains how to use the code in more verbose detail. This would discuss the syntax, the Filter object, the options, etc. It might be possible to adapt the first tutorial to serve this role. Ideally some of the redundancy between the tutorials could be eliminated by subsuming some other concepts into this page (e.g could we explain GPU filtering on that page). Many of the tutorials are halfway between narrative documentation for different features and examples.

A "quickstart" page might also be useful for people who just want to copy and paste something and get started immediately.

I also think we should rename the other "tutorials" as "examples" and put them in a sub directory. The new layout would be like this

docs/examples/index.rst  # links out to all of the examples
docs/examples/example_filter_types.ipynb
docs/examples/...

Above all, whatever organization we choose, the top level page (https://gcm-filters.readthedocs.io), should describe the structure and organization of the documentation, so users can find what they are looking for more easily.