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&gt; > --- > 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.