What's in a Word? - Words to Watch

Locked
User avatar
humvee
Joomla! Master
Joomla! Master
Posts: 14713
Joined: Wed Aug 17, 2005 10:27 pm
Location: Kent, England

What's in a Word? - Words to Watch

Post by humvee » Sat Oct 07, 2006 3:44 pm

Hi all,

A contender for the "Words to Watch" segment - after agreement:

Do we use stylesheet or style sheet ? (07.10.06


To Be Added:

consistent and not consistant (07.10.06)

Andy
Last edited by humvee on Tue Oct 10, 2006 12:08 pm, edited 1 time in total.

rdb
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 139
Joined: Mon Aug 22, 2005 5:21 pm

Re: What's in a Word?

Post by rdb » Sat Oct 07, 2006 6:14 pm

The W3 speaks of "Style sheets" implementations (CSS1, CSS2, XPath, XSLT)
http://www.w3.org/Style/

So my initial suggestion would be to use Style Sheets as opposed to Stylesheets

-- r
-- Joomla! Evangelist

ledzep

Re: What's in a Word?

Post by ledzep » Mon Oct 09, 2006 3:50 pm

I have adjusted the User Manual to Style Sheet(s)

User avatar
visionspin
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 183
Joined: Mon Aug 22, 2005 9:35 pm
Location: Pittsburgh, PA
Contact:

Re: What's in a Word? - Words to Watch

Post by visionspin » Thu Oct 12, 2006 5:10 pm

I will make the edits in Words to Watch...thanks for your input. :)

User avatar
Michelle Bisson
Joomla! Ace
Joomla! Ace
Posts: 1808
Joined: Fri Aug 12, 2005 12:47 am
Location: Quebec City, Canada
Contact:

Re: What's in a Word? - Words to Watch

Post by Michelle Bisson » Fri Oct 13, 2006 4:01 am

Thanks Jennifer!
Michelle Bisson, POPcliQ, http://www.popcliq.com
Joomla / OSM Trademarks Team Member

User avatar
humvee
Joomla! Master
Joomla! Master
Posts: 14713
Joined: Wed Aug 17, 2005 10:27 pm
Location: Kent, England

Re: What's in a Word? - Words to Watch

Post by humvee » Sun Oct 15, 2006 5:14 pm

visionspin wrote: I will make the edits in Words to Watch...thanks for your input. :)
No problem :)

I have a few more which I will put in shortly.

@rdb Thanks for clarification.

Regards

Andy

User avatar
CirTap
Joomla! Explorer
Joomla! Explorer
Posts: 418
Joined: Mon Dec 12, 2005 5:34 pm

Re: Words to Watch - "Email" vs. "e-mail"

Post by CirTap » Mon Oct 16, 2006 10:10 pm

Hi writers,

I have just registered to the "Workshop" site in the hope I'll be able to contribute.

What has always bothered me is "Email" as used in the english language pack of Joomla ever since, and too many translation teams follow this "bad style".

According to some link I found in the Wikipedia Style-Gude reference, here's a nice reading: http://www.theslot.com/email.html

I fully agree with Mr. Walsh, and apparently the documentation team used the same (correct) form: "e-mail".

For the matter of consistancy between Application and documentation: any chance to get this "Email" out of the /language/*.ini files as well?
There are 23 "email"s waiting for a change in:
- en-GB.com_banners.ini
- en-GB.com_mailto.ini
- en-GB.com_registration.ini
- en-GB.com_user.ini
- en-GB.ini

Who's proof-reading the languages files, anyway? :)

Have fun,
CirTap
You can have programs written fast, well, and cheap, but you only get to pick 2 ...

"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams

User avatar
visionspin
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 183
Joined: Mon Aug 22, 2005 9:35 pm
Location: Pittsburgh, PA
Contact:

Re: What's in a Word? - Words to Watch

Post by visionspin » Tue Oct 17, 2006 2:22 am

I am not sure who is proofreading the files, as we are just in charge of the user and administrator manuals and help screens. However, I totally agree with you about e-mail. If you will notice, that is what we have asked people to do in the Words to Watch in the Editorial Style Guide.

??? Do you think the Style Guide or Words to Watch list are not visible enough? Perhaps people are not utilizing them in their proof-reading as they should be for document consistency.

User avatar
humvee
Joomla! Master
Joomla! Master
Posts: 14713
Joined: Wed Aug 17, 2005 10:27 pm
Location: Kent, England

Re: What's in a Word? - Words to Watch

Post by humvee » Tue Oct 17, 2006 11:27 am

visionspin wrote: I am not sure who is proofreading the files, as we are just in charge of the user and administrator manuals and help screens. However, I totally agree with you about e-mail. If you will notice, that is what we have asked people to do in the Words to Watch in the Editorial Style Guide.
This would probably entail getting all the programmers of PHP, MySQL, and probably every other piece of software on the planet to adopt the same principle...Good Luck!
??? Do you think the Style Guide or Words to Watch list are not visible enough? Perhaps people are not utilizing them in their proof-reading as they should be for document consistency.
These are not available to the general Joomla! population anymore. As far as the Documentation Workshop team is concerned, how about doing a re-direction on acceptance of registration so they are fired into the Style Guide and Words to Watch? Is it even possible to attach this document as an add-on to the acceptance email - or at the very least to add the links to these?

You still actually then have the issue of people reading and following them! ;)

Regards

Andy

User avatar
humvee
Joomla! Master
Joomla! Master
Posts: 14713
Joined: Wed Aug 17, 2005 10:27 pm
Location: Kent, England

Re: What's in a Word? - Words to Watch

Post by humvee » Tue Oct 17, 2006 11:36 am

FrontPage...Front-Page...Frontpage...Front Page...

This is a difficult one as there are different ways in use in the program files themselves.

Is there a consistent policy that should be adopted? Some clarification certainly needs to be added to W2W.

Andy

User avatar
humvee
Joomla! Master
Joomla! Master
Posts: 14713
Joined: Wed Aug 17, 2005 10:27 pm
Location: Kent, England

Re: What's in a Word? - Words to Watch

Post by humvee » Tue Oct 17, 2006 11:42 am

home page vs homepage (vs home-page not seen too much of this)

User avatar
CirTap
Joomla! Explorer
Joomla! Explorer
Posts: 418
Joined: Mon Dec 12, 2005 5:34 pm

Re: What's in a Word? - Words to Watch

Post by CirTap » Tue Oct 17, 2006 6:33 pm

Hi,
visionspin wrote: Do you think the Style Guide or Words to Watch list are not visible enough?
well, yes, since they aren't visible at all unless one registers on the workshop site.
visionspin wrote: Perhaps people are not utilizing them in their proof-reading as they should be for document consistency.
Style Guide - Chapter 6 wrote:Consideration means following simple guidelines to make the content accessible to all of the readers, rather than excluding or insulting them based on their gender, nationality, culture, or disability. One of the best ways to make sure your documentation is considerate is to keep the audience in mind as you write or edit the content.
IMHO, the audience are not only proof-readers and editors but the developers and of course 3PD contributing code and information to the whole project. I'm not sure if every single members of the dev-team or other working groups who write any kind of text that appears inside and around Joomla! are aware of the Style guides and have read them.

I think at least the Words-to-Watch-list should be public and also get cross-linked from any corresponding guide like:
- Translation Manual
- Developer Standards
Moste noteably the latter, since 3PD devs are likely to use the same works in their extensions, and they're the first to write documentation for their work. I don't see why such guides should only apply to the official working groups. The examples given in "Words to Watch" should certainly apply to any genuine Joomla! work and become mandatory to every member. They may as well be "recommended" for those willing to create code or write docs in the Joomla! Universe.
Provide tools, examples and information, and people will use them. Easy :)
The documentation team is of cource focussed on Joomla, but there's a lot of great information available, both 3PDs and writers may use in general for any kind of contribution.

As of Joomla! itself, consistency in language style and terminology spans the documentation and the application(s) being documented. They must match, and if that's not possible (i.e. GUI's often have limited space available), a list of official alternatives or abbreviations must be available.
Being a developer myself, I know it's hard to create unambiguous labels and text for a user interface everybody understands, despite using proper english in the first place -- or german in my case.

Since the Workshop requires registration, none of the useful style guides is available to the public. There are many people writing documentation and tutorials, code or whatever. The work, but may not not neccessarily work there for whatever reason -- time is probably the most common, philosophy and concepts are others.
Frankly, from a user's POV, it suxx if the same terms inside an application are spelled different, since extension authors don't have guides like this available to follow. MS and Apple have extensione guideline on how things should look and be called. People feel "at home" if they use applications and documentation that follow the same rules.

The workshop homepage also lacks a "this is what you get if you register" but promotes "this is what you should do" ;) and there's yet another account to create ...

However, I can't think of any reason to lock any audience from this particular type of content, esp. if it contains some sort of vivid information.
Such "not so secret" guides, rules and best practices on writing, programming, and designing about and for Joomla! should be made available at least from one central place, instead of spreading across the dev area and other parts of the help site. That'd need to talk to the folks of the S&I group, but unlike code and data, the promotion of useful information should be redundant so anyone (internal and 3PD) can find it ad-hoc and follow these guides more easiliy -- and willingly. 3Ps may even label their work as "Joomla! standards compliant" ;-)

If W2W and alike must be kept where it is, maybe add a "Guides" section to the public FAQ or the "Offical Documentation" menu, and summarize the available documents, incl. logo usage, press material, and even the forum rules and the code of conduct.

There's so much stuff available, often related but spreading the various Joomla! sites that it would need a professional librarian to organize it :) Do you have one in the team? Maybe ask in the forums or documentation site if someone's willing to consult?
visionspin wrote: I am not sure who is proofreading the files, as we are just in charge of the user and administrator manuals and help screens.
Like any documentation at this scale, the GUI needs a copy editor as well. This also includes the sample data.
The language files are documentation as well, limited in the amount but the first thing users see!
"...keep the audience in mind as you write or edit the content."
If not the documentation team, who else can "guarantee" this content matched the documentation? At the very least, the doc-team must proof-read what the devs put into the INI files.

Have fun,
CirTap
You can have programs written fast, well, and cheap, but you only get to pick 2 ...

"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams

User avatar
Michelle Bisson
Joomla! Ace
Joomla! Ace
Posts: 1808
Joined: Fri Aug 12, 2005 12:47 am
Location: Quebec City, Canada
Contact:

Re: What's in a Word? - Words to Watch

Post by Michelle Bisson » Wed Oct 18, 2006 3:25 am

Thanks for your suggestions.  The Editorial Style Guide is now public on the Help Site as well as the Workshop site.

I hope that you become an active contributor to the doc project.  Our urgent need is for contributors to write new content for the 1.5 Help Screens.
Michelle Bisson, POPcliQ, http://www.popcliq.com
Joomla / OSM Trademarks Team Member

User avatar
CirTap
Joomla! Explorer
Joomla! Explorer
Posts: 418
Joined: Mon Dec 12, 2005 5:34 pm

Re: What's in a Word? - Words to Watch

Post by CirTap » Wed Oct 18, 2006 12:54 pm

Hi Michelle,
Michelle Bisson wrote: Thanks for your suggestions.  The Editorial Style Guide is now public on the Help Site as well as the Workshop site.
thanx a bunch.
Unfortunately, if I'm not logged in I get this error:
  You are not authorized to view this resource.
  You need to login.

Michelle Bisson wrote: I hope that you become an active contributor to the doc project.  Our urgent need is for contributors to write new content for the 1.5 Help Screens.
I'll see what I can do :) First off, I'll scan the pages to get an overview of what's going on and available.

Have fun,
CirTap
You can have programs written fast, well, and cheap, but you only get to pick 2 ...

"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams

User avatar
humvee
Joomla! Master
Joomla! Master
Posts: 14713
Joined: Wed Aug 17, 2005 10:27 pm
Location: Kent, England

Re: What's in a Word? - Words to Watch

Post by humvee » Wed Oct 18, 2006 2:22 pm

humvee wrote: FrontPage...Front-Page...Frontpage...Front Page...
This is a difficult one as there are different ways in use in the program files themselves.
Is there a consistent policy that should be adopted? Some clarification certainly needs to be added to W2W.
Posted by: humvee

home page vs homepage (vs home-page not seen too much of this)
Any chance of getting back to the original topic? Please ;)
Clarity on these two please.

Andy

User avatar
Michelle Bisson
Joomla! Ace
Joomla! Ace
Posts: 1808
Joined: Fri Aug 12, 2005 12:47 am
Location: Quebec City, Canada
Contact:

Re: What's in a Word? - Words to Watch

Post by Michelle Bisson » Thu Oct 19, 2006 2:10 am

I will ask Visionspin to respond as she is responsable for maintaining the Editorial Style Guide.  Thank you!
Michelle Bisson, POPcliQ, http://www.popcliq.com
Joomla / OSM Trademarks Team Member

User avatar
Michelle Bisson
Joomla! Ace
Joomla! Ace
Posts: 1808
Joined: Fri Aug 12, 2005 12:47 am
Location: Quebec City, Canada
Contact:

Re: What's in a Word? - Words to Watch

Post by Michelle Bisson » Fri Oct 20, 2006 3:36 am

thanx a bunch.
Unfortunately, if I'm not logged in I get this error:
  You are not authorized to view this resource.
  You need to login.
Sorry, it is now public access.
Michelle Bisson, POPcliQ, http://www.popcliq.com
Joomla / OSM Trademarks Team Member


Locked

Return to “1.5 Archive”