"how-to" or "howto"

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

Hi :slight_smile:
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 :slight_smile:

[...]

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.

[...]

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.

Hi Tom and everyone --

This is my first time posting to the list. I'm a new reader and user,
but I have a long history and familiarity with Unix and some Linux in
limited technical realms. I'm also a former long-time newspaper copy
editor, used to Associated Press and Guardian style guides, with some
familiarity with Chicago and The Economist and the 90s-era Wired Style
Guide.

I do understand how HOWTO comes about, alongside README files, and I can
get wanting to help evolve a language, as well as the desire for
consistency. But to me, the primary goal of any document or text for the
general public is common understanding, and I think that is the reason
many style guides are very slow to adapt. Aside from filenaming
conventions, I would suggest using "how to" as a verb, and "how-to" as a
noun or adjective. When starting a sentence or in a section heading,
only capitalize the H. When speaking about a textfile, (again, new user
of LO; I don't even know if these files exist), I think HOWTO is is a
fine exception.

My reasoning is based on Associated Press, but equally on my 'ear' and
'eye'. The AP Stylebook issues only a guideline; while it has specific
citations for a lot of applications, here it is up to the editor to
interpret and implement:

hyphen (-) Hyphens are joiners. Use them to avoid ambiguity
or to form a single idea from two or more words.

To me, using the conventional, or mainstream, style form would have
broader ease of understanding; I would rather go old-school than to give
an unfamiliar reader pause and take him away from the content of what he
is trying to digest.

Best,
Rick

[snip]

whoops! Sorry if this had been resolved by the time I posted. It looks
like Thunderbird Conversations split this thread into two for me.

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

Hello

Before I leap in with both feet and make start on some chapters, I would like to know which operating system to use for making screen shots if I have to insert new screen shots. I can easily produce screen shots in Mac OS, Windows or Ubuntu as I do use all three operating systems.

Regards

Peter Schofield

Hi :slight_smile:

I agree that the aim is to be as comfortable to read as possible. i think
the guides need have a balance between being noob-friendly and being
tolerable for geeks.

A lot of computer-savvy users know the term "how-to" and "read-me" and it
would be good to introduce those terms to people that don't already know
them. Many terms are likely to crop-up elsewhere such as forums. As an
initial introduction and gateway into OpenSource programs such as
LibreOffice (and Firefox) 'should' prepare people by introducing such terms.
Using existing widely used guidelines seems sensible unless they are under
copyright or difficult to access or where they perpetuate inaccuracies or
kludges.

For people who don't understand English as a 1st language we would hope that
the official documentation gets translated into something they feel more
comfortable with. MTs (Machine translators) are sometimes hilariously wrong
or inept. Their output needs to be at least proof-read by a human being
that understands implications and nuances of the target language.

Btw you can look at the thread in Nabble to see how your post got treated.
It didn't get split up. At least i don't think it did!
Regards from
Tom :slight_smile:

The order of preference is: Linux, Mac OS X, Windows. Most important
is to use a neutral (primarily silver, grey or similar) theme with
high contrast (such as the so-called "XP-Silver" theme one of our team
put together for Ubuntu several years ago) and the Galaxy icon set.
See here for a bit more info:
http://wiki.documentfoundation.org/Documentation/Production#Sample_screenshots

Recently we had a discussion about whether the "XP-Silver" theme would
install on Ubuntu 11.10 (and how to do it). I don't recall what the
outcome was. IMO the Radiance and Adwaita themes on Ubuntu 11.10 are
okay, though not quite as good as the old "XP-Silver".

I intend to update Chapter 2, Producing LibreOffice User Guides, of
the Contributors’ Guide with this information if we get it resolved
and I ever find time. (Or someone else can update the chapter; but I
don't think I've even brought in Hazel's edits from some months ago.)

--Jean

I've just checked Chapter 5, Style Guide for LibreOffice.org User
Guides, of our Contributors’ Guide and it shows "how-to" as the
preferred term (see the section "Commonly used words"). Not that the
list of terms is immutable...

--Jean