diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml
index 2983c76c770..108967d287b 100644
--- a/nixos/doc/manual/development/development.xml
+++ b/nixos/doc/manual/development/development.xml
@@ -14,6 +14,7 @@ NixOS.
+
diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml
new file mode 100644
index 00000000000..59a287717ac
--- /dev/null
+++ b/nixos/doc/manual/development/writing-documentation.xml
@@ -0,0 +1,147 @@
+
+
+Writing NixOS Documentation
+
+
+ As NixOS grows, so too does the need for a catalogue and explanation
+ of its extensive functionality. Collecting pertinent information
+ from disparate sources and presenting it in an accessible style
+ would be a worthy contribution to the project.
+
+
+
+Building the Manual
+
+ The DocBook sources of the are in the
+ nixos/doc/manual
+ subdirectory of the Nixpkgs repository. If you make modifications to
+ the manual, it's important to build it before committing. You can do
+ that as follows:
+
+ nix-build nixos/release.nix -A manual.x86_64-linux
+
+
+
+ When this command successfully finishes, it will tell you where the
+ manual got generated. The HTML will be accessible through the
+ result symlink at
+ ./result/share/doc/nixos/index.html.
+
+
+
+
+Editing DocBook XML
+
+
+ For general information on how to write in DocBook, see
+
+ DocBook 5: The Definitive Guide.
+
+
+
+ Emacs nXML Mode is very helpful for editing DocBook XML because it
+ validates the document as you write, and precisely locates
+ errors. To use it, see .
+
+
+
+ Pandoc can generate
+ DocBook XML from a multitude of formats, which makes a good starting
+ point.
+
+
+ Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML
+ pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
+
+
+ Pandoc can also quickly convert a single
+ section.xml to HTML, which is helpful when
+ drafting.
+
+
+
+ Sometimes writing valid DocBook is simply too difficult. In this
+ case, submit your documentation updates in a GitHub
+ Issue and someone will handle the conversion to XML for you.
+
+
+
+
+Creating a Topic
+
+
+ You can use an existing topic as a basis for the new topic or create a topic from scratch.
+
+
+
+Keep the following guidelines in mind when you create and add a topic:
+
+
+
+ The NixOS book
+ element is in nixos/doc/manual/manual.xml.
+ It includes several
+ parts
+ which are in subdirectories.
+
+
+
+ Store the topic file in the same directory as the part
+ to which it belongs. If your topic is about configuring a NixOS
+ module, then the XML file can be stored alongside the module
+ definition nix file.
+
+
+
+ If you include multiple words in the file name, separate the words
+ with a dash. For example: ipv6-config.xml.
+
+
+
+ Make sure that the xml:id value is unique. You can use
+ abbreviations if the ID is too long. For example:
+ nixos-config.
+
+
+
+ Determine whether your topic is a chapter or a section. If you are
+ unsure, open an existing topic file and check whether the main
+ element is chapter or section.
+
+
+
+
+
+
+
+
+Adding a Topic to the Book
+
+
+ Open the parent XML file and add an xi:include
+ element to the list of chapters with the file name of the topic that
+ you created. If you created a section, you add the file to
+ the chapter file. If you created a chapter, you
+ add the file to the part file.
+
+
+
+ If the topic is about configuring a NixOS module, it can be
+ automatically included in the manual by using the
+ meta.doc attribute. See for an explanation.
+
+
+
+
+
+
+
+
+
+