[PI] Docs: Potential Future Improvements Overview #3883
Description
📚 Documentation
The Iris docs have been overhauled ready for the Iris 3.0.0 release but I have some ideas on how to improve more....
Small things
☒ Review the steering council documentation, https://scitools.org.uk/organisation.html#organisation-top
- The use of OVERRIDE_TEST_DATA_REPOSITORY is cited in the composed docs but not in the iris.config docstrings. Perhaps it should
- Update the release steps for maintainers to include a tweet announcement.
- Review the Iris wiki on github (https://github.com/SciTools/iris/wiki). This has recently been disabled so the link no longer works. The content includes out of date info and some old release notes documentation.
- Add wsl to installing iris #3885. Include a reference for WSL on the installing Iris page. Useful for users/devs who only have Windows 10, and it works great in my experience.
Ideas
☒ Add a section for a FAQ: Too much upkeep and not enough use-case
☒ Use asciinema to capture some guides. Example for a user on singularity, see https://asciinema.org/~vs
- Add a section for "Why Iris?"
- Add a Glossary
- Consider adding more badges to the README or the docs themselves, where appropriate.
Sphinx extensions
- Consider using if appropriate, https://github.com/djungelorm/sphinx-tabs? This is redundant as sphinx-panels supports this too.
- Documentation homepage, use of panels for visibility to users #3884. Consider using if appropriate, https://sphinx-panels.readthedocs.io/en/latest/