Doc: parent-child convention for installed packages

doc/parent_child_spec.mld

@@ -1,6 +1,8 @@
 {0 Parent/Child Specification}
 This parent/child specification allows more flexible output support, e.g., per library documentation. See {{:https://ocaml.org/packages}ocaml.org/packages}.
 
+{1 Rules}
+
 The rules are;
 
 {ul 
@@ -19,6 +21,8 @@ The rules are;
 {b Note:} The [--pkg <package>] option is still supported for backward compatibility in [odoc >= v2.0.0],
 although it's now equivalent to specifying a parent [.mld] file.
 
+{1 Example}
+
 For example, let's consider [John] whose is [Doe] and [Mark]'s father. [Doe] has
 children, [Max], and page [foo], whereas [Mark] has no children. That is to say,
 [john.mld], [doe.mld], [mark.mld], [max.mld], [foo.ml] respectively. For instance;
@@ -157,3 +161,31 @@ and we shall get
 ]}
 
 For more about [odoc] commands, simply invoke [odoc --help] in your shell.
+
+{1 Convention for installed packages}
+
+Locally, the build system can make arbitrary complex documentation page
+hierarchies.
+However, the generated HTML documentation is generally not installed as part of
+a package. Instead the documentation source code made of [.mld] pages is
+installed and might be used by a different driver.
+
+{2 Convention}
+
+In order for drivers to build consistent documentation for a package, the
+following convention should be followed.
+
+- [.mld] pages are installed in a package's [share] directory, under the
+  [odoc-pages] sub-directory.
+- A page is the parent of every installed pages. The driver can freely name this
+  page, for example it can be named after the package. In what follows, we
+  refer to this page as the [pkg] page.
+- If there is an installed [index.mld] file, the driver has to use it as
+  content for the [pkg] page.
+- If there is no installed [index.mld] page, the driver has to generate some
+  content for the [pkg] page.
+
+This convention is followed by the
+{{:https://github.com/ocaml-doc/voodoo}driver for ocaml.org},
+by the driver {{:https://erratique.ch/software/odig/doc/packaging.html}Odig}
+and by the build system {{:https://github.com/ocaml/dune}Dune}.