Skip to content

Strip unnecessary content

Lyndon Brown requested to merge jnqnfe/live-manual:strip into master

The manual was created as not just a source of user documentation, but project documentation, as per the initial paragraph. But why? Readers of the manual almost exclusively will be users wanting to make use of live-build to build a live image, and thus their interests lie in building and customising live images.

The current manual, in portrait PDF form is over 100 pages in length, with significant chunks of its content being of absolutely relevance to most readers.

Specifically, the unnecessary content extends to (in no particular order):

  • The "style guide", giving guidance on authoring the documentation itself, which is frankly junk imho.
  • The coding style info, which is obviously only relevant to potential contributors.
  • The "project procedures" stuff, which is only relevant to the official Debian images release team.
  • The project contributing notes, which again are only relevant to contributors, and overlaps with similar content in the project wiki.
  • The stuff about how to build the documentation, which is only relevant to maintainers and contributors.
  • The "about project" content which is somewhat obsolete.
  • The list of authors. This is not only of no value to most readers, but has maintenance and fairness issues. Authors can be properly identified from the set of committers in the git repo.
  • The verbose license statement. The documentation is covered by GNU GPL 3+, which is not a document oriented license, but well, we're stuck with it unless permission is obtained from all of the authors to switch to something more appropriate (not that I have any specific one in mind). Be that as it is, it is completely unnecessary to display the text block that we typically embed at the top of code files, especially considering that some of that text makes little sense in a manual. For instance it starts off with "this program", when this is a document not a program. It should be perfectly sufficient to just simply state "license: GNU GPL 3+".

One argument for removing such content is simply that it impacts significantly how daunting the manual appears to users considering reading it. Additional arguments include that it is a complete waste of time for translators to be translating this unnecessry content, increasing likelihood of putting potential translators off from contributing (in terms of volume of work). Time has already been wasted translating it in existing content, and presents a pointless maintenance burden.

It may not be so bad for the "segmented" form of the manual, but bloats significantly the complete form like PDF or single page HTML.

This MR strips the manual down, moving the above content into markdown files in /doc/. Some could perhaps just be deleted, and some maybe could do with editing, but the focus here was just moving it out of the actual manual, and I decided to move/archive it rather than delete.

Additional content that could perhaps be moved out:

  • The chunk of bug reporting content.
  • The installation of live-build guide.

I unfortunately cannot say how many pages the PDF is slimmed down to after this, I get an error originating in /usr/lib/ruby/vendor_ruby/sisu/texpdf.rb hinting at checking my textlive dependencies, which I've been unable to resolve when trying to build PDF form (both before and after my changes).

But, I can say that the /manual/en directory goes from 161.1 KiB down to 130.9 KiB, which is a reduction of 18.75%! So a reasonable guess would be that it cuts the PDF down from ~100 pages to ~80.

Merge request reports