doc: add "Add relevant documentation" guideline

This adds a new section to the contributing guidelines that discusses
how contributions should be documented.

PR #1306

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/contributing.adoc b/doc/contributing.adoc
index a24dff10234..a6c7a3278e7 100644
--- a/doc/contributing.adoc
+++ b/doc/contributing.adoc
@@ -84,6 +84,26 @@ If at all possible, make sure to add new tests and expand existing tests so that
 All contributed code _must_ pass the test suite.
 
 [[sec-guidelines-module-maintainer]]
+
+==== Add relevant documentation
+:docbook: https://tdg.docbook.org/
+:asciidoc: https://asciidoc.org/
+:docbook-rocks: https://docbook.rocks/
+
+Many code changes require changing the documentation as well. Module options should be documented with DocBook. See {docbook-rocks}[DocBook rocks!] for a quick introduction and {docbook}[DocBook 5: The Definitive Guide] for in-depth information of DocBook. Home Manager is itself documented using a combination of DocBook and {asciidoc}[AsciiDoc]. All text is hosted in Home Manager's Git repository.
+
+The HTML version of the manual containing both the module option descriptions and the documentation of Home Manager can be generated and opened by typing the following in a shell within a clone of the Home Manager Git repository:
+
+[source,console]
+$ nix-build -A docs.html
+$ xdg-open ./result/share/doc/home-manager/index.html
+
+When you have made changes to a module, it is a good idea to check that the man page version of the module options looks good:
+
+[source,console]
+$ nix-build -A docs.manPages
+$ man ./result/share/man/man5/home-configuration.nix.5
+
 ==== Add yourself as a module maintainer
 
 Every new module _must_ include a named maintainer using the `meta.maintainers` attribute. If you are a user of a module that currently lacks a maintainer then please consider adopting it.