Open
Description
Problem
With every version update, part of the readthedocs documentation will become out-of-date or even misleading (e.g. #31, 831121d)
All version-specific contents are vulnerable to such problem. For example:
- Pulling new data for new simulation periods. Starting 12.5.0, only pulling new metfields is not enough, because offline emissions is also time-dependent, as discussed in [FEATURE REQUEST] Need better scripts to download data from S3 #25.
- Setting up a custom model version
- Using containers (tied to the model version in container and corresponding input data)
Suggestions
- Collect a list of all version-dependent contents, and remember to update them at each version release.
- Minimize those version-dependent contents. Remove unnecessary pages.
- Go through to entire documentation with a certain schedule, such as every 3-month, or every major release (13.0.0, 14.0.0). Try if all commands still work. Remove outdated & misleading & unnecessary contents.
- Make use of readthedoc versioning so that users can fall back to old docs if the latest one has any problems.
- Explore other best practices for maintaining docs -- for example I found this Sphinx tutorial: Keeping Documentation Up to Date. The same practice is also useful for GCPy.