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 <catcr...@gmail.com> 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: documentation+unsubscr...@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
