Use a modular, deeper structure for doc source files

Registered by Meg McRoberts

In conjunction with the reorganization of the documentation titles, the doc source is being restructured to be deeper and more modular:

- Each source file contains a single header
- The main directory for each “book” contains a file for each Level 1 header (marked by ======= in the rst source). If there are no sub-headings, that file contains the content; if there are subheadings, a same-named subdirectory contains individual files with the contents of the section and the file in the main book directory is an include file that sources those files.
-In the sourcing sub-directory, file names are assigned according to the following scheme:
    - Files with Level 1 headings are prefixed x000; for example, 1000-how-ha-works.rst.
    - Files with Level 2 headings are prefixed xy00; for example, 1300-haproxy.rst.
    - Files with Level 3 and 4 headings continue the scheme. Headings deeper than Level 4 are discouraged.
   - Files that contain a header but no content are discouraged.

The existing doc files have been split into modular files although there is little logic in the assigned names. As the new doc set is implemented, the new naming scheme will be implemented; we will not do a separate project to impose this naming scheme on the existing docs.

Blueprint information

Not started
Dmitry Borodaenko
Meg McRoberts
Needs approval
Meg McRoberts
Series goal:
Accepted for future
Not started
Milestone target:
milestone icon next

Related branches



This process has been completed; all modularized docs have been merged


Work Items

This blueprint contains Public information 
Everyone can see this information.


No subscribers.