some style and formatting issues for discussion

classic Classic list List threaded Threaded
5 messages Options
catdance catdance
Reply | Threaded
Open this post in threaded view
|

some style and formatting issues for discussion

Hi All,

It would be helpful to discuss and agree on some style and formatting
issues that are not fully covered in the Contributor Guide. These are
all small issues but it would be good to have more consistency. If time,
perhaps these issues could be discussed tomorrow. We can then update the
Contributor Guide to reflect this agreement. Here goes:

Menu, title, and status are bars. All others are toolbars. Correct?

Should names of bars/toolbars be capitalized? That is, menu bar or Menu
bar; formatting toolbar or Formatting toolbar?

The names of GUI elements should match what is on the screen. However,
capitalization of those elements is inconsistent. Sometimes only the
first word of the name is capitalized, sometimes other words are also
capitalized. What should the policy be for documentation? Perhaps the UX
folks have a policy that we can follow.

How should GUI elements be formatted? Clearly MenuPath should be used
for instructions such as *View > Toolbars > Drawing.* But what is
considered a menu path? And when should emphasis be used?

What should be used:

  *

    Select Stack series to show cumulative Y values above each other.

  *

    Select *Stack series* to show cumulative Y values above each other.

  *

    Select /Stack series/ to show cumulative Y values above each other.

  *

    Something else?

What should be used:

  *

    Also adjusted is the 3D angle of the disc in the /Perspective/ page
    in the same set of tabs.

  *

    Also adjusted is the 3D angle of the disc in the *Perspective*page
    in the same set of tabs.

  *

    Also adjusted is the 3D angle of the disc in the Perspectivepage in
    the same set of tabs.

What should be used?

  *

    When “Data series as columns” and “First row as labels” are selected
    on the Data Range page

  *

    When *Data series as columns*and *First row as labels*are selected
    on the Data Range page

  *

    When /Data series as columns/and /First row as labels/are selected
    on the Data Range page

Should it be: Step 1 or step 1? Should it be page 1 or Page 1?

I look forward to hearing what people think and imagine that other
people have similar nit-picking issues that they could add.


--
To unsubscribe e-mail to: [hidden email]
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
catdance catdance
Reply | Threaded
Open this post in threaded view
|

Re: some style and formatting issues for discussion

I am posting again with the hope that some people are willing to share
their opinions about these formatting and style issues. When we agree on
these, I think we should add similar examples to the Contributor Guide.

Jean, if you have a chance, your thoughts would be valuable.

On 5/28/2019 2:52 PM, Cathy Crumbley wrote:

>
> Hi All,
>
> It would be helpful to discuss and agree on some style and formatting
> issues that are not fully covered in the Contributor Guide. These are
> all small issues but it would be good to have more consistency. If
> time, perhaps these issues could be discussed tomorrow. We can then
> update the Contributor Guide to reflect this agreement. Here goes:
>
> Menu, title, and status are bars. All others are toolbars. Correct?
>
> Should names of bars/toolbars be capitalized? That is, menu bar or
> Menu bar; formatting toolbar or Formatting toolbar?
>
> The names of GUI elements should match what is on the screen. However,
> capitalization of those elements is inconsistent. Sometimes only the
> first word of the name is capitalized, sometimes other words are also
> capitalized. What should the policy be for documentation? Perhaps the
> UX folks have a policy that we can follow.
>
> How should GUI elements be formatted? Clearly MenuPath should be used
> for instructions such as *View > Toolbars > Drawing.* But what is
> considered a menu path? And when should emphasis be used?
>
> What should be used:
>
>  *
>
>     Select Stack series to show cumulative Y values above each other.
>
>  *
>
>     Select *Stack series* to show cumulative Y values above each other.
>
>  *
>
>     Select /Stack series/ to show cumulative Y values above each other.
>
>  *
>
>     Something else?
>
> What should be used:
>
>  *
>
>     Also adjusted is the 3D angle of the disc in the /Perspective/
>     page in the same set of tabs.
>
>  *
>
>     Also adjusted is the 3D angle of the disc in the *Perspective*page
>     in the same set of tabs.
>
>  *
>
>     Also adjusted is the 3D angle of the disc in the Perspectivepage
>     in the same set of tabs.
>
> What should be used?
>
>  *
>
>     When “Data series as columns” and “First row as labels” are
>     selected on the Data Range page
>
>  *
>
>     When *Data series as columns*and *First row as labels*are selected
>     on the Data Range page
>
>  *
>
>     When /Data series as columns/and /First row as labels/are selected
>     on the Data Range page
>
> Should it be: Step 1 or step 1? Should it be page 1 or Page 1?
>
> I look forward to hearing what people think and imagine that other
> people have similar nit-picking issues that they could add.
>

--
To unsubscribe e-mail to: [hidden email]
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
Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

Re: some style and formatting issues for discussion

Thanks for pushing on this, but I haven’t the energy for style & formatting
guide discussions. I’ve done this two or three times over the OO/LO years
and someone always comes along later and changes things, often unilaterally.

My only formatting suggestion is: keep it all as simple as possible. Most
volunteers don’t follow the guidelines anyway; I know it’s frustrating for
those of us who DO follow guidelines when they are available. Each book
really needs a final, thorough consistency edit by one person - but usually
that doesn’t happen.

I will make a few opinionated notes inline below.

Jean

On Wed, 3 Jul 2019 at 05:18 Cathy Crumbley <[hidden email]> wrote:

> I am posting again with the hope that some people are willing to share
> their opinions about these formatting and style issues. When we agree on
> these, I think we should add similar examples to the Contributor Guide.
>
> Jean, if you have a chance, your thoughts would be valuable.
>
> On 5/28/2019 2:52 PM, Cathy Crumbley wrote:
> >
> > Hi All,
> >
> > It would be helpful to discuss and agree on some style and formatting
> > issues that are not fully covered in the Contributor Guide. These are
> > all small issues but it would be good to have more consistency. If
> > time, perhaps these issues could be discussed tomorrow. We can then
> > update the Contributor Guide to reflect this agreement. Here goes:
> >
> > Menu, title, and status are bars. All others are toolbars. Correct?


Yes, unless I’m forgetting some exceptions.

>
> >
> > Should names of bars/toolbars be capitalized? That is, menu bar or
> > Menu bar; formatting toolbar or Formatting toolbar?


Yes, capitalized. But not capitalize the words “bar” or “toolbar”.


> >
> > The names of GUI elements should match what is on the screen. However,
> > capitalization of those elements is inconsistent. Sometimes only the
> > first word of the name is capitalized, sometimes other words are also
> > capitalized. What should the policy be for documentation? Perhaps the
> > UX folks have a policy that we can follow.


I don’t think it much matters, but generally having the docs match the UI
is, I think, best. One reason the docs are inconsistent is the UI has been
changing.


> >
> > How should GUI elements be formatted?


Should be as simple as possible while still being clear. The vast majority
of readers won’t even notice the formatting.


> Clearly MenuPath should be used
> > for instructions such as *View > Toolbars > Drawing.* But what is
> > considered a menu path? And when should emphasis be used?
> >
> > What should be used:
> >
> >  *
> >
> >     Select Stack series to show cumulative Y values above each other.
> >
> >  *
> >
> >     Select *Stack series* to show cumulative Y values above each other.
> >
> >  *
> >
> >     Select /Stack series/ to show cumulative Y values above each other.
> >
> >  *
> >
> >     Something else?
> >
> > What should be used:
> >
> >  *
> >
> >     Also adjusted is the 3D angle of the disc in the /Perspective/
> >     page in the same set of tabs.
> >
> >  *
> >
> >     Also adjusted is the 3D angle of the disc in the *Perspective*page
> >     in the same set of tabs.
> >
> >  *
> >
> >     Also adjusted is the 3D angle of the disc in the Perspectivepage
> >     in the same set of tabs.
> >
> > What should be used?
> >
> >  *
> >
> >     When “Data series as columns” and “First row as labels” are
> >     selected on the Data Range page
> >
> >  *
> >
> >     When *Data series as columns*and *First row as labels*are selected
> >     on the Data Range page
> >
> >  *
> >
> >     When /Data series as columns/and /First row as labels/are selected
> >     on the Data Range page
> >
> > Should it be: Step 1 or step 1? Should it be page 1 or Page 1?
> >
> > I look forward to hearing what people think and imagine that other
> > people have similar nit-picking issues that they could add.
> >
>
>

--
To unsubscribe e-mail to: [hidden email]
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
Luke (gmail) Luke (gmail)
Reply | Threaded
Open this post in threaded view
|

Re: some style and formatting issues for discussion

What about capturing the most important information about agreed
conventions, writing that in a style aimed at the reader, for inclusion
in an early "How to use this manual" or "About This Manual" intro chapter?

It could be provided in a template document designed to be fleshed out
by volunteers.

Doing that, might:
- make it easier for contributors to get started
- improve the chance the contributor read and used the guidelines
- be useful to the reader
- ensure contributors are using well-formed LO documents
- achieve the goal of improved consistency.

luke


On 11/7/19 5:11 pm, Jean Weber wrote:

> Thanks for pushing on this, but I haven’t the energy for style & formatting
> guide discussions. I’ve done this two or three times over the OO/LO years
> and someone always comes along later and changes things, often unilaterally.
>
> My only formatting suggestion is: keep it all as simple as possible. Most
> volunteers don’t follow the guidelines anyway; I know it’s frustrating for
> those of us who DO follow guidelines when they are available. Each book
> really needs a final, thorough consistency edit by one person - but usually
> that doesn’t happen.
>
> I will make a few opinionated notes inline below.
>
> Jean
>
> On Wed, 3 Jul 2019 at 05:18 Cathy Crumbley <[hidden email]> wrote:
>
>> I am posting again with the hope that some people are willing to share
>> their opinions about these formatting and style issues. When we agree on
>> these, I think we should add similar examples to the Contributor Guide.
>>
>> Jean, if you have a chance, your thoughts would be valuable.
>>
>> On 5/28/2019 2:52 PM, Cathy Crumbley wrote:
>>>
>>> Hi All,
>>>
>>> It would be helpful to discuss and agree on some style and formatting
>>> issues that are not fully covered in the Contributor Guide. These are
>>> all small issues but it would be good to have more consistency. If
>>> time, perhaps these issues could be discussed tomorrow. We can then
>>> update the Contributor Guide to reflect this agreement. Here goes:
>>>
>>> Menu, title, and status are bars. All others are toolbars. Correct?
>
>
> Yes, unless I’m forgetting some exceptions.
>
>>
>>>
>>> Should names of bars/toolbars be capitalized? That is, menu bar or
>>> Menu bar; formatting toolbar or Formatting toolbar?
>
>
> Yes, capitalized. But not capitalize the words “bar” or “toolbar”.
>
>
>>>
>>> The names of GUI elements should match what is on the screen. However,
>>> capitalization of those elements is inconsistent. Sometimes only the
>>> first word of the name is capitalized, sometimes other words are also
>>> capitalized. What should the policy be for documentation? Perhaps the
>>> UX folks have a policy that we can follow.
>
>
> I don’t think it much matters, but generally having the docs match the UI
> is, I think, best. One reason the docs are inconsistent is the UI has been
> changing.
>
>
>>>
>>> How should GUI elements be formatted?
>
>
> Should be as simple as possible while still being clear. The vast majority
> of readers won’t even notice the formatting.
>
>
>> Clearly MenuPath should be used
>>> for instructions such as *View > Toolbars > Drawing.* But what is
>>> considered a menu path? And when should emphasis be used?
>>>
>>> What should be used:
>>>
>>>   *
>>>
>>>      Select Stack series to show cumulative Y values above each other.
>>>
>>>   *
>>>
>>>      Select *Stack series* to show cumulative Y values above each other.
>>>
>>>   *
>>>
>>>      Select /Stack series/ to show cumulative Y values above each other.
>>>
>>>   *
>>>
>>>      Something else?
>>>
>>> What should be used:
>>>
>>>   *
>>>
>>>      Also adjusted is the 3D angle of the disc in the /Perspective/
>>>      page in the same set of tabs.
>>>
>>>   *
>>>
>>>      Also adjusted is the 3D angle of the disc in the *Perspective*page
>>>      in the same set of tabs.
>>>
>>>   *
>>>
>>>      Also adjusted is the 3D angle of the disc in the Perspectivepage
>>>      in the same set of tabs.
>>>
>>> What should be used?
>>>
>>>   *
>>>
>>>      When “Data series as columns” and “First row as labels” are
>>>      selected on the Data Range page
>>>
>>>   *
>>>
>>>      When *Data series as columns*and *First row as labels*are selected
>>>      on the Data Range page
>>>
>>>   *
>>>
>>>      When /Data series as columns/and /First row as labels/are selected
>>>      on the Data Range page
>>>
>>> Should it be: Step 1 or step 1? Should it be page 1 or Page 1?
>>>
>>> I look forward to hearing what people think and imagine that other
>>> people have similar nit-picking issues that they could add.
>>>
>>
>>
>


--
To unsubscribe e-mail to: [hidden email]
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
Steve Fanning Steve Fanning
Reply | Threaded
Open this post in threaded view
|

Re: some style and formatting issues for discussion

In reply to this post by Jean Weber
Cathy,

For what they are worth, here are my thoughts on your queries. I am
relatively new to the team and no expert but I have read the guidelines
contained in the file LibreOffice_6.x_Template.ott and checked what others
have done recently in the 6.0 Getting Started and Writer Guides. I???m sure
other members of the team will advise if I have misinterpreted anything.

I hope that what follows helps.

Q. Menu, title, and status are bars. All others are toolbars. Correct?
SF: The 6.0 Getting Started Guide clearly identifies Menu, Title, and Status
as bars. However the Calc Formula bar should also be considered a bar rather
than a toolbar, the main reason being that it is called a bar in the user
interface and we should not unilaterally rename items in the documentation.
There may be more examples like this in other LibreOffice components but I
am not sufficiently knowledgeable about those components to be able to
readily identify any oddballs at this time.

Q. Should names of bars/toolbars be capitalized? That is, menu bar or Menu
bar; formatting toolbar or Formatting toolbar?
SF: Checking usage in other documents, it is clear that the Menu bar,
Formatting toolbar capitalization is the most frequently used. Therefore I
would recommend following that approach as a sensible option that minimises
future re-work.

Q. The names of GUI elements should match what is on the screen. However,
capitalization of those elements is inconsistent. Sometimes only the first
word of the name is capitalized, sometimes other words are also capitalized.
What should the policy be for documentation? Perhaps the UX folks have a
policy that we can follow.
SF: In my previous existences I have always followed the names used on the
user interface exactly, even if they are less than ideal, inconsistent or
even plain wrong. I believe the user documentation should follow this
strategy to avoid introducing unnecessary confusion for users. If the
Documentation Team doesn???t like something on the GUI, then presumably we can
always raise a bug to suggest an improvement.

Q. How should GUI elements be formatted? Clearly MenuPath should be used for
instructions such as *View > Toolbars > Drawing.* But what is considered a
menu path? And when should emphasis be used?
SF: The LibreOffice_6.x_Template.ott seems to contain reasonable guidelines
about when the Strong Emphasis and Emphasis character styles should be used.
The legacy MenuPath character style isn???t mentioned and so, presumably,
shouldn???t be used. As a starting point I consider the term menu path to
include any navigation path through the options in the Menu bar or any
navigation path through a right-click context menu.

Q. What should be used: Select Stack series to show cumulative Y values
above each other?
SF: Assuming this sentence refers to the Stack series option that appears on
the Calc Chart Wizard after you select the Line chart type??? ???Stack series???
should be written using exactly the same upper and lower case letters as on
the Chart Wizard and should utilise the Strong Emphasis character style.

Q. What should be used: Also adjusted is the 3D angle of the disc in the
/Perspective/page in the same set of tabs?
SF: Assuming this sentence refers to the 3D View dialog that is accessed by
selecting a 3D chart and then selecting Format > 3D View from the Menu bar???
I would suggest rewording slightly and using ???Also adjusted is the 3D angle
of the disc in the Perspective tab on the 3D View dialog???. ???Perspective???
should be in the Emphasis character style and ???3D View??? should be in the
default character style.

Q. What should be used? When ???Data series as columns??? and ???First row as
labels??? are selected on the Data Range page
SF: Assuming this sentence refers to the Data Range page of the Chart
Wizard??? References to ???Data Series in Rows???, ???Data series in columns???,
???First row as label??? and ???First column as label??? should all be in the Strong
Emphasis font.

Q. Should it be: Step 1 or step 1? Should it be page 1 or Page 1?
SF: I would only capitalize the word ???step??? if English requires it (e.g.
first word in sentence) or if it is capitalized on the user interface (e.g.
on Writer???s Mail Merge Wizard). As a specific example, I would not otherwise
capitalize the text ???See step 4??? when this simply refers back to a step in a
procedure described within the document that you are working on. Similarly I
would only capitalize the word ???page??? if English requires it or it is
capitalized on the user interface. Hence I might write ???See page 114 for
more information???.

Regards,

Steve Fanning


--
To unsubscribe e-mail to: [hidden email]
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