What's in a Word? - Words to Watch
- humvee
- Joomla! Master
- Posts: 14704
- Joined: Wed Aug 17, 2005 10:27 pm
- Location: Kent, England
What's in a Word? - Words to Watch
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
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.
-
- Joomla! Enthusiast
- Posts: 139
- Joined: Mon Aug 22, 2005 5:21 pm
Re: What's in a Word?
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
http://www.w3.org/Style/
So my initial suggestion would be to use Style Sheets as opposed to Stylesheets
-- r
-- Joomla! Evangelist
- visionspin
- 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
I will make the edits in Words to Watch...thanks for your input.
- Michelle Bisson
- Joomla! Ace
- Posts: 1773
- Joined: Fri Aug 12, 2005 12:47 am
- Location: Quebec City, Canada
- Contact:
Re: What's in a Word? - Words to Watch
Thanks Jennifer!
Michelle Bisson, POPcliQ, http://www.popcliq.com
Joomla / OSM Trademarks Team Member
Joomla / OSM Trademarks Team Member
- humvee
- Joomla! Master
- Posts: 14704
- Joined: Wed Aug 17, 2005 10:27 pm
- Location: Kent, England
Re: What's in a Word? - Words to Watch
No problemvisionspin wrote: I will make the edits in Words to Watch...thanks for your input.
I have a few more which I will put in shortly.
@rdb Thanks for clarification.
Regards
Andy
- CirTap
- Joomla! Explorer
- Posts: 418
- Joined: Mon Dec 12, 2005 5:34 pm
Re: Words to Watch - "Email" vs. "e-mail"
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
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
"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams
- visionspin
- 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
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.
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.
- humvee
- Joomla! Master
- Posts: 14704
- Joined: Wed Aug 17, 2005 10:27 pm
- Location: Kent, England
Re: What's in a Word? - Words to Watch
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!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.
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?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.
You still actually then have the issue of people reading and following them!
Regards
Andy
- humvee
- Joomla! Master
- Posts: 14704
- Joined: Wed Aug 17, 2005 10:27 pm
- Location: Kent, England
Re: What's in a Word? - Words to Watch
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
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
- humvee
- Joomla! Master
- Posts: 14704
- Joined: Wed Aug 17, 2005 10:27 pm
- Location: Kent, England
Re: What's in a Word? - Words to Watch
home page vs homepage (vs home-page not seen too much of this)
- CirTap
- Joomla! Explorer
- Posts: 418
- Joined: Mon Dec 12, 2005 5:34 pm
Re: What's in a Word? - Words to Watch
Hi,
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?
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
well, yes, since they aren't visible at all unless one registers on the workshop site.visionspin wrote: Do you think the Style Guide or Words to Watch list are not visible enough?
visionspin wrote: Perhaps people are not utilizing them in their proof-reading as they should be for document consistency.
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.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.
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?
Like any documentation at this scale, the GUI needs a copy editor as well. This also includes the sample data.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.
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
"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams
- Michelle Bisson
- Joomla! Ace
- Posts: 1773
- Joined: Fri Aug 12, 2005 12:47 am
- Location: Quebec City, Canada
- Contact:
Re: What's in a Word? - Words to Watch
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.
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
Joomla / OSM Trademarks Team Member
- CirTap
- Joomla! Explorer
- Posts: 418
- Joined: Mon Dec 12, 2005 5:34 pm
Re: What's in a Word? - Words to Watch
Hi Michelle,
Unfortunately, if I'm not logged in I get this error:
You are not authorized to view this resource.
You need to login.
Have fun,
CirTap
thanx a bunch.Michelle Bisson wrote: Thanks for your suggestions. The Editorial Style Guide is now public on the Help Site as well as the Workshop site.
Unfortunately, if I'm not logged in I get this error:
You are not authorized to view this resource.
You need to login.
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.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.
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
"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams
- humvee
- Joomla! Master
- Posts: 14704
- Joined: Wed Aug 17, 2005 10:27 pm
- Location: Kent, England
Re: What's in a Word? - Words to Watch
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.
Any chance of getting back to the original topic? PleasePosted by: humvee
home page vs homepage (vs home-page not seen too much of this)
Clarity on these two please.
Andy
- Michelle Bisson
- Joomla! Ace
- Posts: 1773
- Joined: Fri Aug 12, 2005 12:47 am
- Location: Quebec City, Canada
- Contact:
Re: What's in a Word? - Words to Watch
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
Joomla / OSM Trademarks Team Member
- Michelle Bisson
- Joomla! Ace
- Posts: 1773
- Joined: Fri Aug 12, 2005 12:47 am
- Location: Quebec City, Canada
- Contact:
Re: What's in a Word? - Words to Watch
Sorry, it is now public access.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, POPcliQ, http://www.popcliq.com
Joomla / OSM Trademarks Team Member
Joomla / OSM Trademarks Team Member