LO 7.2 Writer Guide macOS edition

I have created a version of the Writer Guide 7.2 specifically for
users of macOS.
The changes include "translating" keyboard keys from the Windows/Linux
default to their Mac equivalents; replacing Windows/Linux screenshots
with Mac equivalents (most screenshots were already taken from macOS);
rewording some sections as required (removing Windows or Linux
specific instructions). The only major change was about the Print
dialog, which is quite different on macOS. I also amended the covers
to include the words "macOS edition".

I have put a PDF of the compiled book, and ODTs of individual
chapters, in a NextCloud folder (MacOS Edition) under English > Writer
Guide > 7.2. Feel free to review and comment. I'm sure I've missed
something or made some errors; I always do.

Would the team like to have this book as part of the documentation
set? I am unlikely to update it very often, and I am unlikely to
produce a macOS edition of any other books except possibly the Getting
Started Guide - if I have time.
If it's not wanted as an official user guide, I will rebrand it
(different cover, copyright and chapter title pages) and publish it as
a "Taming LibreOffice" book on my website.

Jean

There should be a better way to meet the needs of mac users than a macOS
edition in https://documentation.libreoffice.org/en/english-documentation/.
Other applications manage to produce one set of docs for different
OSs, even if linux screenshots look a bit strange to say Windows users. It
will leave mac users with a general feeling of discontent there are no
current guides for their application/language. I suggest it should be
independent of current guides and the documents should be reviewed in the
context of better meeting macOS needs.

The whole guide preparation process is pretty impressive. Maybe OS-specific
keys and screenshots could be scripted in future guides for custom editions
but I doubt it is justified.

Hi flywire, Jean, All

... Would the team like to have this book as part of the documentation
set? I am unlikely to update it very often, and I am unlikely to
produce a macOS edition of any other books except possibly the Getting
Started Guide - if I have time.

There should be a better way to meet the needs of mac users than a macOS
edition in https://documentation.libreoffice.org/en/english-documentation/.
Other applications manage to produce one set of docs for different
OSs, even if linux screenshots look a bit strange to say Windows users. It
will leave mac users with a general feeling of discontent there are no
current guides for their application/language. I suggest it should be
independent of current guides and the documents should be reviewed in the
context of better meeting macOS needs.

The whole guide preparation process is pretty impressive. Maybe OS-specific
keys and screenshots could be scripted in future guides for custom editions
but I doubt it is justified.

If we add a control variable that hides or show sections/paragraphs depending on the OS, documents will go into a very complex and fragile management scheme where mistakes (e.g. deletion of a controlled paragraph) are easily introduced and unnoticed. Debugging a long document like our guides will be unpleasant at best.

Technically speaking, LibreOffice has all tools for document management (version control, fields, track-changes...) but our team must get used to and it is also a entry barrier for newcomers.

The Help has a control scheme (<switch>, <switchinline>) for macOS where Ctrl key is changed to Command key and the menu "Tools-Option" is changed to "LibreOffice - Preferences". Those are 99.99% of all differences in Help between OS versions.

Regards

PS: @Jean: you may want to do a search "Tools - Option" in the macOS version.

In the future I will try a Help build patch where the switch/switchinline are ignored. I suggest to add the macOS-specific information into the guides rather than produce separate guides.

Ilmari

The main differences between macOS and Windows/Linux dialogs are the Print dialogs. The other dialogs have minimal differences and should not cause a problem for macOS LO users

Also the keyboard shortcuts are different and the main difference is Command for Mac and Ctrl for Windows/Linux. The keyboard shortcuts are covered in Appendix A.

I use macOS version, but have a Linux version of LO running in Ubuntu. Doing it this way I can capture Linux screenshots, but has also given me the experience of working in the different versions. I think adding macOS instructions would complicate the user guides and make it more difficult to upgrade the user guides to the latest versions of LO.

I disagree with adding specific macOS instructions to the user guides and I do not think it is necessary to produce macOS user guides.

Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team

Jean et.. al.,

I took a look at the complete pdf and it looks good. As a macOS user I
would prefer this guide than the Linux/Windows-oriented "generic" guide ...

I do see where Jean is trying to help the user (which is what documentation
is about) - macOS users are a bit left out by using guides where there is a
small note on the bottom of page 3 and then the keys not marked on their
keyboard are mentioned more than 100 times throughout the book. That is
very user-unfriendly. Now, geeks know about these keys and might not even
need such a basic, GS guide. But we are talking about users needing these
guides - i.e. not familiar with the concept of an office suite, editing
documents, creating slides, adding formulas to sheets, printing ...

I also see what the others replied - but I do not see this as a problem for
the documentation project - this is a special guide, it can be published
alongside the main guides (and if there will not be time and will for new
ones - the will just not be there). So we could simply add a section to the
documentation site where this could be published. It would not mess with
the line of "official", "generic" guides, yet it would serve a specific
public. "Special guides", "Dedicated guides", "Guide incubator", etc.

From the download numbers and the publishing orders one would be able to
assess if such guides make sense in the long run for the documentation team
and if they can be made more automatically from the "generic" guides.

Another possibility would be to add a specific appendix for macOS users
about printing to all the GS guides. Others have mentioned in this thread
that this is the real difference between the OS', yet no one proposed any
solution to this gap in usability of the guides - don't the macOS users
deserve proper printing instructions in the GS guides?

To sum it up: can't we support Jean's effort, make a difference with the
"regular" guides in presenting it to the public and base our decision on
the success of the guide?

Ilmari, could you please elaborate: what do you intend to patch regarding
the help build?

Happy 2022,
Martin

V V ned., 2. jan. 2022 ob 13:18 je oseba Ilmari Lauhakangas <
ilmari.lauhakangas@libreoffice.org> napisala:

Ignoring these so everything is written for every OS: https://wiki.documentfoundation.org/Documentation/Understanding,_Authoring_and_Editing_Openoffice.org_Help/3#switch

The current approach with operating system parameters also causes technical issues (JavaScript redirect needed to view Help to begin with).

Ilmari

Hello Jean

The macOS WG72 is available in the documentation download website.

Your effort must be published. No doubts.

https://documentation.libreoffice.org/en/english-documentation/

Kind regards
Olivier

Ilmari,

just to make sure I understand correctly - you want to change all the help
strings that have these switches and so they will appear untranslated or
fuzzy and translators of l10n teams will have to manually check and
(re)translate them (130 teams * hundreds/thousands of strings)?

Lp, m.

V V ned., 2. jan. 2022 ob 19:39 je oseba Ilmari Lauhakangas <
ilmari.lauhakangas@libreoffice.org> napisala:

Thank you, Olivier. I will create the print version now.
Jean

V V ned., 2. jan. 2022 ob 19:39 je oseba Ilmari Lauhakangas <
ilmari.lauhakangas@libreoffice.org> napisala:

  > Ilmari, could you please elaborate: what do you intend to patch
regarding
  > the help build?

Ignoring these so everything is written for every OS:

https://wiki.documentfoundation.org/Documentation/Understanding,_Authoring_and_Editing_Openoffice.org_Help/3#switch

The current approach with operating system parameters also causes
technical issues (JavaScript redirect needed to view Help to begin with).

Ilmari

--
To unsubscribe e-mail to: documentation+unsubscribe@global.libreoffice.org
Problems?
https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette
List archive: https://listarchives.libreoffice.org/global/documentation/
Privacy Policy: https://www.documentfoundation.org/privacy

> Ilmari,
>
> just to make sure I understand correctly - you want to change all the help
> strings that have these switches and so they will appear untranslated or
> fuzzy and translators of l10n teams will have to manually check and
> (re)translate them (130 teams * hundreds/thousands of strings)?

No, to make the HTML generator write everything in the switch statements. Now, I'm not sure how well this will work for every writing system in the world as it would require adding parentheses and spaces in the case of switchinline elements, but it's worth a shot.

Ilmari

Hello Team

After giving it some thought about macOS users (me being one), following is a couple of ideas.

1. Printing — add in the macOS print dialog pages to each user guide and explain the options available. I will put together a draft for this after I have finished the Draw Guide this week.

2. Keyboard Shortcuts — rename Appendix A to windows & Linux Keyboard Shortcuts. Create a new Appendix B for macOS Keyboard Shortcuts.

Any thought would be welcome.

Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team

I think these are both good ideas, in particular the addition of the printing info for macOS.

I doubt most users are reading the documentation like a novel, beginning to end, so having a note in the preface and even an appendix covering macOS shortcuts still might not help the user who looks up a specific task they need to do, and gets confused by the keyboard shortcuts in the chapter they're looking at. For that user, a separate guide for macOS solves the problem, but I agree with the previous comments about the degree of work needed to maintain separate OS guides, and the potential fragility introduced.

Would it be too messy to have a brief statement at the start of each chapter reminding the reader to reference the shortcuts specific to their OS in the appropriate appendix?

Rachel