Documentation Team Meeting Minutes February 18th 2021 at 18:00 UTC.

Documentation Team Meeting Minutes February 18th 2021 at 18:00 UTC.

Presents: Ahmad, Dave Burton, Olivier, Rafael Lima, Tuomas Hietala

Telegram Channel
https://t.me/joinchat/ALeRuUFCxyZY0wzoddldWQ

Live TDF Jitsi Room
https://jitsi.documentfoundation.org/tdfdocteam

Completed items:

Pending items:
    + Change in workflow (DB)
    + Objective: rewrite/improve Calc Database functions Help (SF)
       + Update on database ranges

        + Macros have been moved to wiki, translations enabled

        + Chapter updated and available for review (SF)

    + Contributor guide
       + Needs reviews of Peter S on Chap 2.
    + Plan to get chap 1 update in wiki by next meeting (Dave)

News:

Topics and Discussion:

* A 5th character style for the Guides Templates?(OH)
   + purpose: Highlight UI widgets in text
Examples:
... Select 'Add File Section to Document' radio button to...
... click 'New Style From Selection' icon ...
   + Suggestion 1: LibreOffice Mono 11pt (Dave Barton, PVT)
   + Suggestion 2: LibreOffice Mono 11pt, italic, light gray background (OH)
   + Bring the proposal to NC (DB), let other comment
AI: Upload sample in Cloud and annouce in mailing list

* Question: Do we need Guides as a web pages?
Sample https://newdesign.libreoffice.org/guides/pt/CG70/CG7005.html
   + Effort is already measured and feasible (OH)
      + will write a blog post on How-To convert Chapter to HTML page (OH)
      + Semi automated, need few manual interventions (OH)
   + HTML page will get attention from search engines (Rafael)
      + SE don't crawl PDF nicely (Rafael)
   + Write a summary explaining the process, leave details for later (Dave)
   + Avoid obvious question: "Is it nice?" (OH)

Meeting ajourned

Next meeting : *THURSDAY* March 4th 2021 at 18:00 UTC.

Hi Team

* A 5th character style for the Guides Templates?(OH)
   + purpose: Highlight UI widgets in text
Examples:
... Select 'Add File Section to Document' radio button to...
... click 'New Style From Selection' icon ...
   + Suggestion 1: LibreOffice Mono 11pt (Dave Barton, PVT)
   + Suggestion 2: LibreOffice Mono 11pt, italic, light gray background (OH)
   + Bring the proposal to NC (DB), let other comment
AI: Upload sample in Cloud and annouce in mailing list

I uploaded a sample file (actually based on the current 7.0 template
file) with a proposal for the 5th character style to represent dialog
box object ("widgets").

the file is
https://nextcloud.documentfoundation.org/s/JpM8wq95naG4dZj

and can be visited also in the /Contributor Resources/ folder.

Regards

I've apparently missed previous discussion on this new (5th) character
style. Why is it needed? What is the expected or intended value added
with this new style? I looked at the sample. Seems to me like a lot of
fiddly work for writers/reviewers to change the applied style as we
update chapters to v7.1, with no apparent (to me) benefit to the
reader.

Jean

Hello

I have had a look at the proposal for a new character style and I am inclined to agree with its inclusion onto the template, but not italic.

I presume the choice of Liberation Mono font is to match the font used on the LO dialogs. If the answer to this is yes, then the new character style should also be Liberation Mono regular and not italic. There is enough of a difference between Liberation Mono and Liberation Sans for the character stye to be noticed. An italic version looks too much like the Emphasis character style already in use.

Regards
Peter Schofield
Technical Writer, Document Foundation
psauthor@gmail.com

Hello

Another think about the new character style and here are my thoughts.

I think Widget is not informative enough as a name and suggest UI Text, or something similar.

In UI dialogs you can have two levels of UI text, for example from the Position and Size dialog.
  Position — main section in bold text
    Position X — sub-section in normal text
    Position Y — sub-section in normal text
  Size — main section in bold text
    Width — sub-section in normal text
    Height — sub-section in normal text

Therefore there should be two new character styles — UI Text Bold and UI Text Normal.

As you can see, my suggested new name clearly identifies when this character style should be used.

Regards
Peter Schofield
Technical Writer, Document Foundation
psauthor@gmail.com

I agree with Jean,

this means also additional work for all translation teams, when updating
guides' translation from older versions to 7.1 ...

Lp, m.

napisala:

I am not a translator, but as I understand it, Olivier proposed this
5th. character style mainly for the benefit of translators, see:
https://www.mail-archive.com/documentation@global.libreoffice.org/msg16009.html

While I have many other reservations about the guide documentation
template, I don't believe it will involve much additional effort.
Looking back through some recently published guides there appears to be
a mixed approach to the character style used for naming UI objects
(widgets), where some have the emphasis style and others have the
default style.

Dave

While I agreed with Peter's previous proposal for the 5th. character
style to be Liberation Mono regular, not emphasis (italic), I don't see
the need for any extended character styles.

The whole purpose of the Documentation Template is for all the guides to
have a consistent set of agreed styles and style naming we all use.
However, I have just been looking back through some recently published
guides, where there appears to be a number of additional character
styles invented "on the fly" and duplicated names added for identical
styles.

In light of the above, trying to reach any kind of consensus on a new
guide template is a totally futile exercise and I don't intend to make
any further comment on the subject.

Dave

Hello Team,

Some comments on the Team Meeting Minutes:

About the guides as web pages, I'm all in favour. I believe that by doing
this, we can improve the accessibility of the guides.
About the new character style, I can see that this could help the
contributors by defining it once for all how we address to these items,
but, should it be implemented, I would suggest the Liberation Mono, 11 pt,
italic, without the gray background.

Although it was not discussed in the previous meeting, I would like to give
some suggestions about the workflow.

Considering these three factors:
i. We do not have a fixed number of contributors and we are usually in
shortage of people;
ii. A new LO release is launched every 06 months; and
iii. All of the guides are very well written and were much reviewed in the
past.

How about we start to work with deadlines to publish the new guides? We
just make sure that all of the new features stated in the Release Notes and
the errors pointed are covered, and establish a deadline for the
publication of each chapter.

In my opinion, this could improve the user experience by publishing the
guides closer with the new LO releases.

Would love to hear opinions on this matter.

Best regards,
Felipe Viggiano

At first I was inclined to agree with Olivier about a new character format for widgets. After doing a couple of tests, I think there should be rethink on this new character format.

Reason being is simple. There is already a character format that uses Liberation Mono as a font and that is Code. Yes, the Widget character format could you use an italic version of Liberation Mono. In my opinion, the difference is not enough to distinguish the Widget character format from Code character format. Code text is always written in a mono spaced font and we should keep with that thinking.

Character formats Strong Emphasis and Emphasis could easily be used fo user interface text. I already use Strong Emphasis and Emphasis when naming the main option and sub-option titles in a dialog, and the distinction is enough. In the LO chapter template, Strong Emphasis is also used for dialog buttons.

Regards
Peter Schofield
Technical Writer, Document Foundation
psauthor@gmail.com