Draft Proposal for a 6.x Guides Template

Another "little" LO Documentation task I set for myself over the weekend
was to draft a proposal for a template for the 6.x series guides, which
I have now completed and uploaded to:
https://nextcloud.documentfoundation.org/f/81381

Basically my draft is only an adaptation of Jean's original LO6.0
template. My draft is liberally scattered with comments, some in
response to Jean's original comments.

So what changes are proposed? The  main points are:

  * The question of image anchoring within a frame remains open. It may
    be that we have a need for 2 different anchors for electronically
    published chapters/guides and another for (Lulu) paper printed guides.

  * Wherever possible I have used "Document Properties" and other fields
    to automate the updating of documents.

  * In 2 of Jean's original comments, she makes valid recommendations to
    have additional character styles (LOMenu Path and LOKeystroke) for
    the possible requirement of style changes in future guides. I
    propose removing these additional styles because our documentation
    revision time frame does not really justify these extra styles and
    they only serve to complicate guide style formatting and confuse
    contributors as to when and which style to use. For a little
    simplification, I am proposing these character styles be removed and
    the identical default "*Strong Emphasis*" and "/Emphasis/" styles be
    used instead.

  * Our current guides give little information to the reader about the
    content/layout of the chapter/guide, So I have inserted a new
    section, which includes macOS/other OS key equivalents, moving it
    fro the "Copyright" page. Here I leave it to contributors to decide
    what Information might be most useful to readers in understanding
    what the chapter content/layout provides, although it might be that
    we could create some kind of boilerplate outline to be used.

  * For the benefit of seriously color vision impaired people (like
    myself) I have changed the background and text color of the
    "Caution" heading. To you color vision perfect folks who find this
    change glaringly obnoxious, I say do what I have to do every day,
    "/live with it/".

  * Jean's original comment proposed increasing the Numbering styles
    beyond 3 levels. Checking through previous guides I can find no
    evidence of where we have needed or used numbering levels beyond
    level 3. My proposal is not to add more levels.

  * Jean's original comment proposed that we describe various levels for
    "Mixed Lists". Again, after checking through previous guides I can
    find no evidence of where we have needed or used mixed lists. My
    proposal is to not define any "Mixed Lists" styles.

  * I have added a comment in reply to Jean's original comment regarding
    "Simple Lists" which should be self evident.

  * Likewise, the "Text Body Intro" style might have some value if the
    the paragraph above or below spacing were substantially different
    from the default "Text Body" style. My proposal is to remove the style.

Here I feel it necessary to make it absolutely clear that if any of the
above might seem that I am attacking Jean's work on this template, I am
definitely NOT. I have the greatest respect for Jean's many years of
contributing to this project and for creating the core of this template,
which I seriously doubt I could have done myself from scratch.

I know that some members of the Doc's Team are keen to give this
template's styles a "LO" or similar prefix, but I have opted to stay, as
much as possible, with default styles, because giving what are
essentially default styles new names does not automatically update the
styles used in a document the template is applied to, which in turn
requires more editing.

Would those of you having access to Nextcloud please take a look at the
draft template and discus this at the next docs meeting or post back to
the list if you think anything should be changed or done differently.

Thanks & Regards
Dave

Hi Dave,

Your revision of the template is quite helpful. Some of my thoughts follow below.

Cathy

Another "little" LO Documentation task I set for myself over the weekend
was to draft a proposal for a template for the 6.x series guides, which
I have now completed and uploaded to:
https://nextcloud.documentfoundation.org/f/81381

Basically my draft is only an adaptation of Jean's original LO6.0
template. My draft is liberally scattered with comments, some in
response to Jean's original comments.

So what changes are proposed? The  main points are:

   * The question of image anchoring within a frame remains open. It may
     be that we have a need for 2 different anchors for electronically
     published chapters/guides and another for (Lulu) paper printed guides.

We should agree on how to handle this. I suggest talking about this Wednesday.

   * Wherever possible I have used "Document Properties" and other fields
     to automate the updating of documents.

   * In 2 of Jean's original comments, she makes valid recommendations to
     have additional character styles (LOMenu Path and LOKeystroke) for
     the possible requirement of style changes in future guides. I
     propose removing these additional styles because our documentation
     revision time frame does not really justify these extra styles and
     they only serve to complicate guide style formatting and confuse
     contributors as to when and which style to use. For a little
     simplification, I am proposing these character styles be removed and
     the identical default "*Strong Emphasis*" and "/Emphasis/" styles be
     used instead.

I wonder about eliminating the Keystroke and MenuPath styles. This is for two reasons:

1. While you are concerned about adding those styles, the guides are
    already using them. My understanding is that AltSearch does not find
    character styles, so changing those styles could be time consuming.
2. As I believe Jean has mentioned, eliminating these two character
    styles (by replacing them with Emphasis and Strong Emphasis, which
    it sounds like have the same properties) prevents them from being
    used in a future redesign.

Perhaps I don't understand well enough why you propose eliminating these styles. Do you see clear benefits to reducing the number of styles?

   * Our current guides give little information to the reader about the
     content/layout of the chapter/guide, So I have inserted a new
     section, which includes macOS/other OS key equivalents, moving it
     fro the "Copyright" page. Here I leave it to contributors to decide
     what Information might be most useful to readers in understanding
     what the chapter content/layout provides, although it might be that
     we could create some kind of boilerplate outline to be used.

I imagine that most people look at the guides for help with particular issues. From looking at the table of contents, they can see what is contained in each chapter.
Thus, I am not sure that there is a need for more introductory information at the beginning of a chapter.

   * For the benefit of seriously color vision impaired people (like
     myself) I have changed the background and text color of the
     "Caution" heading. To you color vision perfect folks who find this
     change glaringly obnoxious, I say do what I have to do every day,
     "/live with it/".

I think the Caution heading looks fine.

by the way, when I initially downloaded the document from Nextcloud, the orange background of the Caution banner was not visible, so the yellow text was not readable. I just tried it again and the orange banner is visible. Perhaps this was a LOO glitch.

* Jean's original comment proposed increasing the Numbering styles
     beyond 3 levels. Checking through previous guides I can find no
     evidence of where we have needed or used numbering levels beyond
     level 3. My proposal is not to add more levels.

I am not clear about what Jean was referring to when she indicated that list numbering should be revised.

Where possible, I have cut back on the numbering/bullet levels, as I think they are sometimes not needed and make the text look cluttered. I am not sure that there is a need to add more levels.

* Jean's original comment proposed that we describe various levels for
     "Mixed Lists". Again, after checking through previous guides I can
     find no evidence of where we have needed or used mixed lists. My
     proposal is to not define any "Mixed Lists" styles.

I don’t have a sense of the need. We can always create a style if needed, but perhaps Jean knows of some instances where this would be helpful.

* I have added a comment in reply to Jean's original comment regarding
     "Simple Lists" which should be self evident.

I am not clear about the need for this style. Why wouldn't simple bullets be used?

* Likewise, the "Text Body Intro" style might have some value if the
     the paragraph above or below spacing were substantially different
     from the default "Text Body" style. My proposal is to remove the style.

I don’t know what the Text Body_List_ Intro style would be used for, since there are already intro styles for numbered and bulleted lists.

  Here I feel it necessary to make it absolutely clear that if any of the
above might seem that I am attacking Jean's work on this template, I am
definitely NOT. I have the greatest respect for Jean's many years of
contributing to this project and for creating the core of this template,
which I seriously doubt I could have done myself from scratch.

I know that some members of the Doc's Team are keen to give this
template's styles a "LO" or similar prefix, but I have opted to stay, as
much as possible, with default styles, because giving what are
essentially default styles new names does not automatically update the
styles used in a document the template is applied to, which in turn
requires more editing.

Would those of you having access to Nextcloud please take a look at the
draft template and discus this at the next docs meeting or post back to
the list if you think anything should be changed or done differently.

Thanks & Regards
Dave

Hi Cathy,

Thanks, your comments and observations are much appreciated.

It's getting late here and I need a bit of time to accurately formulate
my replies, so I will answer in the next 12-18 hours.

Regards
Dave

Hi Cathy, all,

Sorry I haven't replied sooner, but I have been out of action for almost
a week and no docs work, or most anything else, during that time.

I am trimming my replies down to just the salient points.

Dave

Hi Dave,

Your revision of the template is quite helpful. Some of my thoughts
follow below.

Cathy

So what changes are proposed? The  main points are:

* The question of image anchoring within a frame remains open. It may
     be that we have a need for 2 different anchors for electronically
     published chapters/guides and another for (Lulu) paper printed
guides.

We should agree on how to handle this. I suggest talking about this
Wednesday.

Sorry I couldn't make the meeting, but it would be good if we can can
find a workable compromise. It seems this issue has been creating
difficulties for some time [1].

* In 2 of Jean's original comments, she makes valid
recommendations to
     have additional character styles (LOMenu Path and LOKeystroke) for
     the possible requirement of style changes in future guides. I
     propose removing these additional styles because our documentation
     revision time frame does not really justify these extra styles and
     they only serve to complicate guide style formatting and confuse
     contributors as to when and which style to use. For a little
     simplification, I am proposing these character styles be removed
and
     the identical default "*Strong Emphasis*" and "/Emphasis/"
styles be
     used instead.

I wonder about eliminating the Keystroke and MenuPath styles. This is
for two reasons:

1. While you are concerned about adding those styles, the guides are
   already using them. My understanding is that AltSearch does not find
   character styles, so changing those styles could be time consuming.
2. As I believe Jean has mentioned, eliminating these two character
   styles (by replacing them with Emphasis and Strong Emphasis, which
   it sounds like have the same properties) prevents them from being
   used in a future redesign.

Perhaps I don't understand well enough why you propose eliminating
these styles. Do you see clear benefits to reducing the number of styles?

My workaround for the AltSearch extension has been to run it in AOO,
where it functions perfectly. Today I have been following the 6.2 QA bug
hunt and I decided to install and check out the AltSearch extension.The
good news is that I had a 100% success rate searching for various
character styles in 25-30 randomly selected documents.Hopefully this is
not a fluke and the extension will work under 6.2 for everyone.

My motivation for a new (redesigned) template is twofold:

1. Simplification. For new documentation contributors there are already
    enough "/mental gymnastics/" and "/gotchas/" to work out, as you
    recently discovered with the question of indexing. Any small things
    we can do to make contributing easier has to be a move in the right
    direction. From the reader's perspective it is of no interest
    whether or not the correct style has been applied to a visually
    identical aspect of a document, he/she only wants clear readable
    information.

2. Standardization: The more we work with modified in-built
    (standard/default) styles the easier it will become apply our
    template to updates of the documentation. Having renamed variants of
    the in-built styles only creates additional work. This is the
    situation we currently faced with in the Calc guide, where the last
    published edition was for LO 4.1 created with a template riddled
    with OOo and other renamed style references. Had we tried to stay
    with in-built and standard named styles in the past our styling
    workload would now be substantially reduced. Yes, there will always
    be the need for an exception, but the more we standardize the easier
    our future workflow will become.

As for future changes of documentation design, please go to ODFAuthors
and grab a copy of any ODT file for OOo 3.0 (published 2013). Ignoring
the colors and the naming convention used, everything is
(unsurprisingly) pretty much identical to our present day publications.
Which suggests that Jean and other contributors of the day got the basic
outline correct and I have not read any proposals for a major deviation
from that outline for the future.

* Our current guides give little information to the reader about the
     content/layout of the chapter/guide, So I have inserted a new
     section, which includes macOS/other OS key equivalents, moving it
     fro the "Copyright" page. Here I leave it to contributors to decide
     what Information might be most useful to readers in understanding
     what the chapter content/layout provides, although it might be that
     we could create some kind of boilerplate outline to be used.

I imagine that most people look at the guides for help with particular
issues. From looking at the table of contents, they can see what is
contained in each chapter.
Thus, I am not sure that there is a need for more introductory
information at the beginning of a chapter.

I am OK with dropping that option.

* For the benefit of seriously color vision impaired people (like
    myself) I have changed the background and text color of the
    "Caution" heading. To you color vision perfect folks who find this
    change glaringly obnoxious, I say do what I have to do every day,
    "/live with it/".

I think the Caution heading looks fine.

Good. I was concerned it might be a bit "/over the top/" for folks with
normal color vision.

by the way, when I initially downloaded the document from Nextcloud,
the orange background of the Caution banner was not visible, so the
yellow text was not readable. I just tried it again and the orange
banner is visible. Perhaps this was a LOO glitch.

Yes, the "/trick/" we use for rendering note, tip and caution heading
icons doesn't always work consistently on every system, but the PDF
output always displays correctly.

* Jean's original comment proposed increasing the Numbering styles
    beyond 3 levels. Checking through previous guides I can find no
    evidence of where we have needed or used numbering levels beyond
    level 3. My proposal is not to add more levels.

I am not clear about what Jean was referring to when she indicated
that list numbering should be revised.

I confess that I responded to that in some degree ignorance, but
checking through previous guides, there appeared to be no requirement
for numbering levels greater than the 3 defined in the 6.0 template.

Where possible, I have cut back on the numbering/bullet levels, as I
think they are sometimes not needed and make the text look cluttered.
I am not sure that there is a need to add more levels.

* Jean's original comment proposed that we describe various levels for
    "Mixed Lists". Again, after checking through previous guides I can
    find no evidence of where we have needed or used mixed lists. My
    proposal is to not define any "Mixed Lists" styles.

I don’t have a sense of the need. We can always create a style if
needed, but perhaps Jean knows of some instances where this would be
helpful.

No I don't see the need, but creating styles "/on-the-fly/" can bring
it's own problems when books are updated.

* I have added a comment in reply to Jean's original comment regarding
    "Simple Lists" which should be self evident.

I am not clear about the need for this style. Why wouldn't simple
bullets be used?

Agreed.

* Likewise, the "Text Body Intro" style might have some value if the
    the paragraph above or below spacing were substantially different
    from the default "Text Body" style. My proposal is to remove the
style.

I don’t know what the Text Body_List_  Intro style would be used for,
since there are already intro styles for numbered and bulleted lists.

If I were to try and second guess Jeans thinking, it might be to set
spacing above/below the paragraph for better line separation.

Many thanks for taking time to check over the template proposal and for
your input.

[1] https://nedcad.nl/en/libreoffice-writer-for-technical-documentation/
    and https://bugs.documentfoundation.org/show_bug.cgi?id=79234

OK scratch that. While running some more checks I picked out the
published ODT chapter GS6000 Preface, searched for character style
LOMenuPath and the extension fell over. So back to my workaround.

Dave