What's in a Word? - Words to Watch

[humvee]

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

[rdb]

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

[ledzep]

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

[visionspin]

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

[Michelle Bisson]

Thanks Jennifer!

[humvee]

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

[CirTap]

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

[visionspin]

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.

[humvee]

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

[humvee]

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

[humvee]

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

[CirTap]

Hi,

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.

Perhaps people are not utilizing them in their proof-reading as they should be for document consistency.

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?

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

[Michelle Bisson]

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.

[CirTap]

Hi Michelle,

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.

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

[humvee]

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

[Michelle Bisson]

I will ask Visionspin to respond as she is responsable for maintaining the Editorial Style Guide.  Thank you!

[Michelle Bisson]

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.