Doc: parent-child convention for installed packages

This convention is already in use by Odig, Voodoo and Dune. It needs to
be specified as it needs to change in order to support assets and
complex hierarchies.

Co-authored-by: Paul-Elliot <[email protected]>

doc/parent_child_spec.mld

@@ -157,3 +157,35 @@ 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.
+- [index.mld] is the parent of every other pages. The driver can freely rename
+  this page, for example, it can be named after the package.
+- Other pages are children of the [index.mld] page.
+
+If no [index.mld] is installed, it's the driver's responsibility to generate
+it.
+
+When the rendering of source code is enabled, the source tree will be named
+[source] and will be a child of [index.mld]. As a consequence, no page can be
+named [source.mld].
+
+This convention is followed by the drivers
+{{:https://erratique.ch/software/odig/doc/packaging.html}Odig}
+and {{:https://github.com/ocaml-doc/voodoo}ocaml.org}
+and by the build system {{:https://github.com/ocaml/dune}Dune}.
+