Suggestions to improve LightningCLI documentation #13249
Description
📚 Documentation
With the recent complete overhaul of the documentation where things were split into expertise levels, some parts now seem misplaced or even incorrect. Here are a few suggestions to improve the documentation related to LightningCLI.
-
The first issue that I see is that there is no introduction. Why should someone use LightningCLI? There is too much emphasis on "reducing config boilerplate" and LightningCLI provides much more than reduction of boilerplate. Furthermore, it is perfectly possible to do everything in python files, so why bother with config files and CLIs? LightningCLI is about hyperparameters, reproducibility and best practices (e.g. separate code from configuration).
-
Currently in master, before the LightningCLI section there is one on hyperparameters that describes how to implement CLIs with argparse. Anyone new to lightning will see this first and most likely use that. Only a long time later would realize that the same could be done with LightningCLI and requiring much less effort. LightningCLI should be introduced where the hyperparameters is first mentioned. And the argparse documentation be renamed to something like legacy CLI and recommend to use LightningCLI instead.
-
In the old version of the documentation, the automatic save of the config is described at the beginning. Now it is barely mentioned. This is a central feature and one of the reasons why people should use LightningCLI for experiments.
-
For the new structure of documentation, there was a bit of careless renaming and copy pasting. For example the section "Reproducibility with the LightningCLI" is not really something I would expect in a FAQ. And also the last two paragraphs where pasted from elsewhere which are not related to reproducibility. Another example is that the section "Argument linking" was renamed to "Connect two config files". Using a different terminology would be fine. But the new title is very misleading. That feature is not about connecting two config files.