Add "Updating Documentation" to the contribution guide (#3009)

* explain how to update the documentation

* use relative link instead of url

docs/contributing/index.md

@@ -84,4 +84,36 @@ cd ./tests/qemu-tests/ && ./tests.sh
 ```
 
 ## Updating Documentation
-TODO
+All the documentation is written in markdown files in the `./docs/` folder. The docs are built into a website using [mkdocs](https://www.mkdocs.org/) (you may see the configuration in `./mkdocs.yml`), pushed to the gh-pages branch, and published via [github pages](https://pages.github.com/). All of this happens in the CI.
+
+In general, for your PR to be accepted you will only need to [Update the auto-generated documentation](#update-the-auto-generated-documentation).
+
+### Update the auto-generated documentation
+The `./docs/commands`, `./docs/functions`, and `./docs/configuration` folders are automatically generated[^1] by extracting the necessary information from the source code. If your changes modify things like a command's description, a configuration's valid values, a [convenience function's](../functions/index.md) arguments - i.e. pretty much anything that's user-facing - you must run
+```{.bash .copy}
+./scripts/generate-docs.sh
+```
+to update the documentation. Commit these changes in a separate commit.
+
+If you forget to do that the CI will detect a discrepency between the documentation and source code (using the `./scripts/verify-docs.sh` script, which you may also invoke yourself) and prevent your PR from being merged (until you push new changes, re-running the CI).
+
+### Manual updates
+Of course, if you wish to update some other part of the documentation, you may simply modify the necessary markdown files. All autogenerated files (or parts of files) will have noticable markers written as markdown comments, for instance:
+```md
+<!-- THIS PART OF THIS FILE IS AUTOGENERATED. DO NOT MODIFY IT. See scripts/generate-docs.sh -->
+```
+In case you want to add something that cannot be cleanly viewed from the debugger, like a video, screenshot, or long example, every command markdown file also has a dedicated part at the bottom for hand-written text which you can use. The `./scripts/generate-docs.sh` script will never delete these hand-written parts, so if you are for instance renaming a command you will have to transfer this part by copy pasting it to the new file.
+
+If you wish to preview the documentation locally, you may do so by running:
+```{.bash .copy}
+./scripts/docs-live.sh
+```
+The build will take some time due to the `Source` section being built. You may disable this by temporarily commenting these lines
+```
+  - api-autonav:
+      modules: ['pwndbg']
+      nav_section_title: "Source"
+```
+in the `mkdocs.yml` file. This will provide much faster build times (but make sure not to commit those changes!). Visit `http://127.0.0.1:8000/pwndbg/` to see the docs. Note that the `Home` section will not be available (it is generated in the CI by copying the README.md), and the site will lack the version selector.
+
+[^1]: Actually, the `./docs/configuration/index.md` file is hand-written, and the intro text to the `./docs/functions/index.md` file is defined in the doc generating file's source code.