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 <pkre...@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.
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 < > gets a vote from
me! Better readability in raw form and organization are further icing on
the cake.
