Help Writer's Guidelines

Hi All,

I believe that in order to make help as uniform/consistent/professional as a possible, a help writer's guidelines needs to be created to guide users who modify help to write in a particular style.

It should address things like the below and more

1. How a user or document should be addressed, as sometimes we use 'you' or 'in a document' (e.g. "You can also set the view") and sometimes we use 'the user' or 'in the document' (e.g. "These paths can be edited by the user.")

2. Preferred words and phrases.

I agree. I am trying to improve a page at the moment, and it is not easy to
see at one place what the original author meant. This may be a translation
problem, and I realise that it is difficult if the translator is not an
educated native speaker of the target language (in this case, UK English).
Also, there are frequent grammatical errors, again I suspect because of
translation. Having said that, the quality of the LO documentation is a lot
better than some I've seen.

Is it worth while producing our own guidelines here? Googling on "technical
writing guidelines" produces a lot of hits, and it might be worth while
looking at these to see how relevant they are.

Hi Peter,

ptoye schrieb:

I agree. I am trying to improve a page at the moment, and it is not easy to
see at one place what the original author meant. This may be a translation
problem, and I realise that it is difficult if the translator is not an
educated native speaker of the target language (in this case, UK English).

The help pages are all in US-English. UK-English is a translation. Translation are not made in files directly, but translation are done via Pootle. https://translations.documentfoundation.org

Kind regards
Regina

Hi Peter,

Hi Peter,

ptoye schrieb:

I agree. I am trying to improve a page at the moment, and it is not
easy to
see at one place what the original author meant. This may be a
translation
problem, and I realise that it is difficult if the translator is not an
educated native speaker of the target language (in this case, UK
English).

The help pages are all in US-English. UK-English is a translation.
Translation are not made in files directly, but translation are done via
Pootle. https://translations.documentfoundation.org

That said, if you're able to improve both languages, it would be great :slight_smile:
Cheers
Sophie

There is _Chapter 5 Style Guide_ in _The LibreOffice Contributor's Guide_.

To supplement those guidelines, it recommends:
* _The Chicago Manual of Style_. University of Chicago Press;
* _Read Me First! A Style Guide for the Computer Industry_. Sun
Microsystems;
* _The Modern Language Association (MLA) guidelines_;

I'll grant that the absence of a specific edition of _The Chicago Manual
of Style_, or specific edition, and version of _The MLA Guidelines_
might be result in stylistic differences between contributors, if they
use different editions/versions of those texts.

I've a dim memory of a different set of guidelines, from the days of OOo
1.x, that was used outside of the group that became ODFAuthors.

jonathon

toki wrote

There is _Chapter 5 Style Guide_ in _The LibreOffice Contributor's Guide_.

To supplement those guidelines, it recommends:
* _The Chicago Manual of Style_. University of Chicago Press;
* _Read Me First! A Style Guide for the Computer Industry_. Sun
Microsystems;
* _The Modern Language Association (MLA) guidelines_;

jonathon

Are the documents you mention available on the Web? I found the Chicago
Manual of Style, but my browser has an adblocker and the download failed.

MLA seems more oriented towards academic than technical writing.

All three books are commercially distributed. You should be able to
find them on Amazon, or your usual ebook vendor.

jonathon