Re: [PATCH 06/32] docs: formatdomain: Split out <devices>

On 7/27/20 2:58 AM, Peter Krempa wrote: > On Fri, Jul 24, 2020 at 11:23:58 -0500, Jonathon Jongsma wrote: > > 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. > I think there's only one disadvantage of doing so. It's breaking > existing links. There are so many broken links in blog posts, product reviews, news articles, and even the direct results of google searches these days that I think it's a losing battle. Would it be possible to create a nearly-empty shell of the original document that just contained redirects to the new locations of the content, then use a different name for the base page of the new version to avoid conflict? > I opted to keep the otput identical including keeping > existing links to prevent any risks of additional bikeshedding on the > series as it's already attracting conflicts. > > I'm all for splitting up the docs and removing all the anchor points I > had to add to keep links working. > Anything to avoid having to type all those &lt; &gt; gets a vote from me! Better readability in raw form and organization are further icing on the cake.