Help Writer's Guidelines

classic Classic list List threaded Threaded
7 messages Options
jphilipz jphilipz
Reply | Threaded
Open this post in threaded view
|

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.

--
Yousuf 'Jay' Philips

--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
ptoye ptoye
Reply | Threaded
Open this post in threaded view
|

Re: Help Writer's Guidelines

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.
Peter
Regina Henschel Regina Henschel
Reply | Threaded
Open this post in threaded view
|

Re: Help Writer's Guidelines

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

--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
sophi sophi
Reply | Threaded
Open this post in threaded view
|

Re: Help Writer's Guidelines

Hi Peter,
Le 20/11/2015 17:00, Regina Henschel a écrit :

> 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 :)
Cheers
Sophie

--
Sophie Gautier [hidden email]
GSM: +33683901545
IRC: sophi
Co-founder - Release coordinator
The Document Foundation

--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
jonathon-6 jonathon-6
Reply | Threaded
Open this post in threaded view
|

Re: Help Writer's Guidelines

In reply to this post by jphilipz


On 30/10/2015 21:24, Yousuf 'Jay' Philips wrote:

> as a possible, a help writer's guidelines needs to be created to guide users who modify help to write in a particular style.

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


--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
ptoye ptoye
Reply | Threaded
Open this post in threaded view
|

Re: Help Writer's Guidelines

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.
Peter
jonathon-6 jonathon-6
Reply | Threaded
Open this post in threaded view
|

Re: Help Writer's Guidelines



On 24/11/2015 12:32, ptoye wrote:

>> 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_;

> Are the documents you mention available on the Web?

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

jonathon


--
To unsubscribe e-mail to: [hidden email]
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted