diff --git a/docs/contributing.adoc b/docs/contributing.adoc
index 54dc2692..3a1805f2 100644
--- a/docs/contributing.adoc
+++ b/docs/contributing.adoc
@@ -94,11 +94,11 @@ All contributed code _must_ pass the test suite.
 [[sec-guidelines-module-maintainer]]
 
 ==== Add relevant documentation
+:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
 :docbook: https://tdg.docbook.org/
 :asciidoc: https://asciidoc.org/
-:docbook-rocks: https://berbiche.github.io/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.
+Many code changes require changing the documentation as well. Module options should be documented with {nixpkgs-markdown}[Nixpkgs-flavoured Markdown]. Home Manager is itself documented using a combination of {docbook}[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:
 
diff --git a/docs/release-notes/rl-2311.adoc b/docs/release-notes/rl-2311.adoc
index c546d37a..4947b809 100644
--- a/docs/release-notes/rl-2311.adoc
+++ b/docs/release-notes/rl-2311.adoc
@@ -5,12 +5,14 @@ This is the current unstable branch and the information in this section is there
 
 [[sec-release-23.11-highlights]]
 === Highlights
+:babelfish: https://github.com/bouk/babelfish
+:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
 
 This release has the following notable changes:
 
 * When using <<opt-programs.fish.enable>>, the setup code
 for <<opt-home.sessionVariables>> is now translated
-with https://github.com/bouk/babelfish[babelfish].
+with {babelfish}[babelfish].
 This should result in significantly faster shell startup times
 but could theoretically break
 if you have very complex bash expressions in a session variable.
@@ -20,9 +22,16 @@ Please report any issues you experience.
 has been supplanted by `release.json`,
 which contains more information about the branch.
 If you have any external code reading this file,
-please migrate to using `release.json` instead.
+please switch to consuming `release.json` instead.
 The `.release` file will be removed in 24.05.
 
+* Home Manager has migrated to using
+the upstream Nixpkgs `lib.nixosOptionsDoc` processor
+for option documentation.
+If you have any external Home Manager modules,
+their option descriptions and literal examples should be translated
+to {nixpkgs-markdown}[Nixpkgs-flavoured Markdown].
+
 [[sec-release-23.11-state-version-changes]]
 === State Version Changes