Re: [PATCH 06/32] docs: formatdomain: Split out <devices>
On Thu, 2020-07-23 at 15:21 +0200, Peter Krempa wrote:
Start splitting the massive document into smaller pieces using the
.. include:: directive.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatdomain-devices.rst | 5053
++++++++++++++++++++++++++++++++
docs/formatdomain.rst | 5054 +----------------------------
----
docs/meson.build | 5 +-
3 files changed, 5058 insertions(+), 5054 deletions(-)
create mode 100644 docs/formatdomain-devices.rst
So, this is already a nice improvement for maintenance, but I wonder if
it wouldn't be good to go even farther and split up the giant document
for the website as well? For instance, the other day, I was looking up
some information in this document about the XML format of network
interfaces. I was looking for a particular word (can't remember what it
was now) so I tried a Ctrl+F to search for the word on the page. Of
course it gave me results from thousands of lines away that were
relevant to e.g. CPU allocation instead of network interfaces.
In addition, some of the sections are so long, with so many sub-
headings (that all look similar to the main headings) that it can be
really cumbersome to navigate and difficult to notice where one section
ends and the next begins.
I understand that there are advantages to having it all on one page as
well, but I'm not sure whether they outweigh the disadvantages.
Jonathon