[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [libreoffice-documentation] Re: some style and formatting issues for discussion


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???.


Steve Fanning

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

Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License (MPLv2). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.