Improve documentation

CHANGELOG.md

@@ -6,6 +6,10 @@
 
   - A bug in handling prepended escape characters in docstrings
 
+- Changed
+
+  - Improved documentation
+
 - Full diff
   - https://github.com/jsh9/pydoclint/compare/0.3.7...0.3.8
 

README.md

@@ -150,6 +150,9 @@ If you'd like to use _pydoclint_ for your project, it is recommended that you
 read these additional notes
 [here](https://jsh9.github.io/pydoclint/notes_for_users.html).
 
+Specifically, there is a section in the additional notes on how to easily adopt
+_pydoclint_ for existing legacy projects.
+
 ## 5. Notes for developers
 
 If you'd like to contribute to the code base of _pydoclint_, thank you!

docs/config_options.md

@@ -163,26 +163,27 @@ return annotation in the function signature are consistent.
 ## 12. `--baseline`
 
 Baseline allows you to remember the current project state and then show only
-new errors, ignoring old ones. This can be very useful when you'd like to
+new violations, ignoring old ones. This can be very useful when you'd like to
 gradually adopt _pydoclint_ in existing projects.
 
-The path to the file is expected. It is recommended to add this option to
-config file. (The default config file is `pyproject.toml`.)
+A path to the file is expected. It is recommended to add this option to config
+file. (The default config file is `pyproject.toml`.)
 
 ```toml
 [tool.pydoclint]
 baseline = "pydoclint-baseline.txt"
 ```
 
-If `--generate-baseline True` (or `--generate-baseline=True`) is passed,
-_pydoclint_ would generate a file that contains all current errors of project.
-If `--generate-baseline` is not passed (default value is `False`), _pydoclint_
-would read your baseline file, and ignore all errors specified in that file.
+If `--generate-baseline=True` (or `--generate-baseline True`) is passed,
+_pydoclint_ will generate a file that contains all current violations of your
+project. If `--generate-baseline` is not passed (default value is `False`),
+_pydoclint_ will read your baseline file, and ignore all violations specified
+in that file.
 
 ## 13. `--generate-baseline` (default: `False`)
 
-Required to use with `--baseline` option. If `True`, generate file, that
-contains all current errors of project.
+Required to use with `--baseline` option. If `True`, generate the baseline file
+that contains all current violations.
 
 ## 14. `--config` (default: `pyproject.toml`)
 

docs/index.md

@@ -150,6 +150,9 @@ If you'd like to use _pydoclint_ for your project, it is recommended that you
 read these additional notes
 [here](https://jsh9.github.io/pydoclint/notes_for_users.html).
 
+Specifically, there is a section in the additional notes on how to easily adopt
+_pydoclint_ for existing legacy projects.
+
 ## 5. Notes for developers
 
 If you'd like to contribute to the code base of _pydoclint_, thank you!

docs/notes_for_users.md

@@ -9,6 +9,7 @@
 - [3. Notes on writing type hints](#3-notes-on-writing-type-hints)
 - [4. Notes on writing Sphinx-style docstrings](#4-notes-on-writing-sphinx-style-docstrings)
 - [5. Notes for Google-style users](#5-notes-for-google-style-users)
+- [6. How to adopt _pydoclint_ more easily in legacy projects](#6-how-to-adopt-pydoclint-more-easily-in-legacy-projects)
 
 <!--TOC-->
 
@@ -171,3 +172,18 @@ But do not worry: here are some config options to tweak:
 configurable options of _pydoclint_, and
 [here](https://jsh9.github.io/pydoclint/how_to_config.html) is how to configure
 _pydoclint_.
+
+## 6. How to adopt _pydoclint_ more easily in legacy projects
+
+If you have large legacy projects, adoting a new linter may be daunting: you'll
+see hundreds or even thousands of violations at first.
+
+Fortunately, _pydoclint_ offers a "baseline" feature, which ignores existing
+violations for now, and will only report new violations.
+
+To use this feature, you only need to generate a "baseline violations" file
+(containing the hundreds or thousands of existing violations) once, and save it
+somewhere in your repo.
+
+For more details, please check out
+[this section](https://jsh9.github.io/pydoclint/config_options.html#12---baseline).