Date: prev next · Thread: first prev next last
2011 Archives by date, by thread · List index


Hello

Being a new boy to the team, I thought I would contribute to this little discussion.

In my opinion it should be "how to" and "read me". This would help people who do not have English 
as their first language. I have had experience of computer terms causing confusion with people who 
English language knowledge is limited. Also using "how to" and "read me" will help during 
translation in these modern times now that translation software is used.

There are several other customs, phrases or words that should not be used, but listing those will 
take some thought and time.

Regards

Peter Schofield


On 6 Nov 2011, at 10:11, Tom Davies wrote:

Hi :)
I think that those terms might be very familiar to geeks, Gnu&Linux users and some people that 
have quite technical understanding of computers but not to 'normal' mainstream people.  

We have an opportunity to introduce people to those terms gently but also to help push the 
language to evolve a little in a direction we like.

I like CamelCase but all capitals looks ugly to me.  In txting, emailing, mailing-lists and so on 
it seems to be considered shouting so i think we should avoid it where possible.  

My preference would be for how-to and read-me as adjectives, not nouns, in order to help 
mainstream pedants understand the documentation.  In titles i prefer How-To and Read-Me in order 
to be more consistent with other words written in Title Case.  Obviously some titles are all 
capitals and that is probably how HOW-TO and READ-ME started.  

Just because other people, such as MicroSoft, do things badly doesn't mean we need to continue 
using their way.  Language evolves.  
Regards from
Tom :)

--- On Sun, 6/11/11, Dennis E. Hamilton <dennis.hamilton@acm.org> wrote:

From: Dennis E. Hamilton <dennis.hamilton@acm.org>
Subject: RE: [libreoffice-documentation] "how-to" or "howto"
To: documentation@global.libreoffice.org
Date: Sunday, 6 November, 2011, 1:24
I suspect it the rule has to do
(hah!) with the adjective rule as well as the desire to
avoid confusion with some sort of verbing.  I think the
nouning of it is typical English language vocabulary
creativity.

One factor in being consistent, of course, is to assist
translation.

I never saw HOWTO until I was looking up something on a
Linux CD one time.  I had seen man pages for years
before, of course.

Enough speculation!

Your mention of "style guide" reminded me that there is a
Microsoft Manual of Style for Technical Publications, though
I don't know if it has been kept up.  I had to look at
three wrong choices before I found it in my disorganized
bookshelves.  It actually has "how-to" in the index.

Here is the Entry:

   "how-to vs. how to

   "   Hyphenate as an
adjective (as in 
       'how-to books'), but use
two words 
       as an adverb plus
infinitive (as 
       in 'This is how to format
your disk').

   "   In headings and
titles, do not 
       capitalize the 't', as in
'How-tos, 
       Tips, and Tricks' or 'How
to Format 
       Your Disk.' "

Notice that they don't address nouning, but they use
"How-tos".  (The so-called computer dictionary is
worse.  Fortunately or unfortunately, the dictionary
has no entries with title in the how* range.  Clearly
Bill Gates did not proof-read any of this or some serious
howlers would have been eliminated.  Bill is very
astute concerning language and clarity.)

Citation:

  Microsoft Corporation.  Microsoft Manual of
Style for Technical Publications, 2nd edition. Microsoft
Press (Redmond WA: 1998).  ISBN 1-57231-890-2 pbk with
CD-ROM.

Experimentation:

I thought I might try searching the CD-ROM version of the
document. There is a Microsoft .chm version, but it's search
treats "how-to" as two separate words.  Bummer. Ahah,
they talk about "readme files" not "read-me files" but that
is probably a typographical issue, since the name of the
file is being referenced.  I suspect that is the ONLY
case where "howto" is usable, as well as fully capitalized,
when it is about files having a particular name or the
application that coughs up such files (the howto command).

Laughs:

I tried running the install of the book on the CD-ROM using
Windows 7 64-bit :).  The installer said it needed to
install IE 4.0 in order to operate.  I declined. 
It looked so 1990s too.  Wow.

Well that was fun.

- Dennis

-----Original Message-----
From: Jean Weber [mailto:jeanweber@gmail.com]

Sent: Saturday, November 05, 2011 16:37
To: documentation@global.libreoffice.org
Subject: Re: [libreoffice-documentation] "how-to" or
"howto"

Thanks, Dennis. Although I don't consider Wikipedia a
definitive
source, it's always nice when it agrees with me. ;-)

I note this sentence in the Wikipedia article you cited:
'The correct
way to write it in English is "how-to", but it is common
practice to
write it as "HOWTO" in the Linux community.' That explains
to me why
many people on this project are used to the all-caps
version. However,
the majority of LO's users are Windows users and,
therefore, I assume
most the readers of our documentation are Windows users;
they are less
likely to be familiar with Linux conventions.

Unfortunately, no style guide citation is given for the
statement 'The
correct way to write it in English is "how-to",' and I've
been unable
to find anything about this in a quick look through my
style guides.
Another possibility is to use "how-to" as an adjective, not
a noun:
for example, "a how-to guide" instead of "a how-to" or "a
list of
how-to guides" instead of "a list of how-tos".

--Jean

On Sun, Nov 6, 2011 at 06:36, Dennis E. Hamilton
<dennis.hamilton@acm.org>
wrote:
You have Wikipedia on your side, <http://en.wikipedia.org/wiki/HowTo>.

The HOWTO as a companion of FAQ and README is
noted.  I also think there is affinity with the
MAN-page Unixism, <http://en.wikipedia.org/wiki/Man_page>, although it
is apparently uncommon to use "man" full-capitalized.

North America goes off daylight savings time in about
13 hours.  Hoo Haa.  Now if I just go to bed early
anyhow!

  - Dennis

-----Original Message-----
From: Jean Weber [mailto:jeanweber@gmail.com]
Sent: Saturday, November 05, 2011 12:57
To: documentation@global.libreoffice.org
Subject: Re: [libreoffice-documentation] "how-to" or
"howto"

On Sunday, November 6, 2011, Marc Paré <marc@marcpare.com>
wrote:
I just wanted to ask if there is an agreed view on
whether to use the
term "how-to" or "howto" or "HOWTO" (all uppercase) on
our LibreOffice
pages?

I believe that the convention is "HOWTO" much in
the same way that we use
"FAQ" in uppercase. Is this how it is being used in
documentation?

I just wanted to ask for the sake of consistency
on our web pages too.

Cheers,

Marc


I prefer "how-to" as a generic term. It's not
like  FAQ, which is an
acronym or initialism. I haven't researched this in
style guides,, however,
so I'm not (yet) dead set on it. I don't recall if the
term is in our own
style guide (which isn't fully up to date); I'll check
that later.

--Jean

--
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
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

--
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
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


-- 
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
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

-- 
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
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


-- 
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
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



-- 
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
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

Context


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.