Talk:In-House Style/Resolved

This page contains discussion from Talk:Kb:In-House Style of issues that have (I think) been resolved. I'm moving them here to clear up some of the clutter, so it's easier to see what still needs to be decided regarding the In-House Style. If you want to re-open discussion on any of these issues, please do it on the other page, not here. --Wintogreen 00:34, 27 Mar 2005 (PST)

Rules; article titles

hao2lian, are you aware that the Rules now contradict all the improvements that people have suggested on the Talk:Rules page? Now the Rules say that the awful " : " category separator nonsense is required (Point 2.2), and that every word in the title should be capitalized (Point 2.1). This appears to have been a relatively recent change (Oct 2004). It means that the in-house style is not consistent with the rules. IMO the rules are wrong on both these issues, and the alternatives outlined in the Talk:Rules page and reflected in the in-house style are far better. --Mozcerize 06:07, 20 Feb 2005 (PST)

I root for the non-subpage ones and parenthetical product names when needed (e.g. "(Firefox)"). I think we'll need to merge the style rules back into the Rules article once the dust settles. --hao2lian

How would this work when an article applies to two products but not all three? For instance, sometimes there are articles that apply to Thunderbird and the Suite but not Firefox, or Firefox and the Suite but not Thunderbird. Are you going to use "article title (Firefox & Mozilla Suite)"? --wintogreen

I would be against "(Firefox and Mozilla Suite)". When it applies to browsers, but not mail, or mail but no browsers, just omit the parentheses. In more complex cases, an article without parentheses may apply to majority of products, and link to articles for the rest of products. This is not perfect solution, but it's much better than space-colon-space one. --asqueella

FWIW, I was the one who "rewrote" the Rules back in October, bringing back the yucky " : " for naming. This was something Kerz had specified in the original Rules in January '04 and which most contributors had been following even after someone else rewrote the Rules in March '04. It seemed stupid to have these revised rules on file when people were continuing to follow the old rules, so I reset them to Kerz's original idea. That said, I'm not a fan of the "space colon space" nomenclature and would be glad to see it replaced with something less clumsy.

Once the new naming scheme is decided, it would be wise to rename all the existing kb articles to comply with it (assuming that this won't break all the kb-internal links). That, more than anything else, will make clear to people what the actual rules are. That didn't happen with the March '04 Rules revision, and as a result that revision was a flop. --wintogreen

I supported you when you reverted Rules back in October, but now when there are more contributors that care about kb and like the newest rules better, I think it's time to change Rules again.

I agree the articles with colons in their name should all be renamed, but it's not always easy to do, because some parts of kb are not very high-quality and there are duplicate articles. In fact, it's very time-consuming process. I hope we'll sort this out eventually. --asqueella

Hi wintogreen! I agree. (I was one of those guilty of perpetuating the " : " despite the March 04 revisions, simply because no-one else was following them. I have now stopped ;-). The bulk-renaming procedure is necessary.

You raise an important point with the (Firefox) thing. I have been thinking about this for a day or two, and I'm not too happy with any of the solutions that I thought of! One possibility is to have pages without (Firefox) and then section them according to application. However, this could make some pages unwieldy. One could go further and replace the sectioning with an "Applies to: " disclaimer at the top of each and every article, and then encourage editors to not mention specific applications in the article but just refer to "the application" instead. However, this could be unpopular. A third possibility is to create other pages such as "article title (Thunderbird)" which simply redirect to "article title (Firefox)". However, this means that the Thunderbird user sees no mention of Thunderbird anywhere in the article!

[A related discussion on writing articles for more than one product continues in its own section below!]

--Mozcerize

This KB is really suffering from a poor decision at the start to split each area (Firefox, Mozilla, Thunderbird, etc) into FAQ, Issues and Tips, hence resulting in silly subcategories like "Firefox : Tips : Mouse Clicks". (Silly because an FAQ is just a Tip rephrased as a question, so it could equally well have been "Firefox : FAQ : What are the mouse shortcuts?".) Indeed, one can see that many links are the same in the FAQ and Tip areas. The use of " : FAQ : " and " : Tip : " subcategories really should be killed off. The primary aim of the KB should be to make it easy to find information. At the moment it is hard to find information, because poorly-designed second-level subpages make it necessary to check out FAQs and Tips and Issues because there's nothing obvious to distinguish between the three.

--Mozcerize 06:07, 20 Feb 2005 (PST)

Articles that apply to two or more products

I'm basically against writing articles to fit two or more products, since I think it's more confusing for the many not-so-technically inclined users who drift into the kb from the forums or a link at mozilla.org. Better to just give people the info the need about the product they have a question about. If the article also applies to the Suite, then why not create a duplicate article for the Suite, with the Suite-specific menus and pathnames are correctly inserted into the article? It's more work to administer separate product articles like this, but it seems more end-user-friendly to me. --wintogreen

wintogreen, I agree with you completely. Using separate articles for the Suite/Firefox/Thunderbird is the most user-friendly way of organizing the kb. Ideally, we should have three separate kbs for each of those products.

Unfortunately, there are very few dedicated contributors (like you) that are up to the task of maintaining a separate version of kb for given product (I'm not). And nobody from "outside" visitors is going to apply their corrections to all versions of given article. I'm not sure I'm willing to spend time keeping various versions of pages in sync (as I mentioned above in my reply in the previous section, it takes a lot of time).

That's why I believe that merging articles - when it is possible and doesn't create much confusion (like the Profile Folder) - is a good idea. Something like conditional #includes would be super. --asqueella

Mm, OK. I guess we can't all be me. Neither can I, for that matter. I stopped being a dedicated kb contributor when TB 1.0 came out. Just decided to chime in here on the Rules/Style guidelines when I saw all the commotion. :-) --wintogreen

But more to the point (since I assume this trend will continue anyway): it would be a good idea to clarify in the In-House Style or Rules what kinds of articles should be written/edited to fit the Suite. From what I've seen so far, the articles that have been Suite-ified are ones that refer to files/pathnames but not Thunderbird or Firefox menus (e.g., the Profile Folder article). This makes sense. If the article refers to FF/TB menus and menu sequences, to make it fit the Suite you'd have to insert the corresponding Suite menus into the article, and that will make the it ugly and confusing for end-users. Some clarity in the Style guidelines would be helpful here. Wintogreen 07:38, 27 Feb 2005 (PST)

Issues to be resolved

This is an attempt to concisely list up some of the various issues related to articles dealing with two or more products. Wintogreen 10:03, 27 Feb 2005 (PST)

1. Are combined product pages really the best way to go? [no, but yes]
2. Which articles to adapt to the Suite: only those that do not refer to FF/TB menu choices?
3. Article titles: what's the least awkward solution?
4. Categories: can these be used to help resolve the issue with article titles?
5. Categories and auto-generated blurbs saying "This article applies to...": sometimes the blurbs need to say a bit more than this
6. Referring to products in article text: say "the application" instead of "Firefox/Thunderbird/Mozilla Suite"?

Capitalization of common terms

We should set rules for capitalization of common terms like Location Bar, Search Bar, Inbox etc. (in article text). Should both words be capitalized? Should the first word only be capital? Should it be all-lowercase? --asqueella

To continue the theme of using the Firefox help file as a style guide, I vote that both words are capitalized. --Unarmed 20:26, 26 Feb 2005 (PST)

Agreed. These things are essentially proper nouns when used in this context. --Mozcerize

File names

How should paths and file names be marked? I'm against using <code> tags for that; they're for code. Perhaps <tt>? Bold? --asqueella

mozilla.org goes with <code class="filename"> fwiw, but I don't feel strongly one way or the other. I don't think that there is too much of an advantage avoiding <code> purely for semantic reasons, since both <tt> and bold are purely presentational anyhow. I would prefer a monospace font though. --Unarmed 20:32, 26 Feb 2005 (PST)

email vs e-mail

I like e-mail better. Both variants are used. Your opinions? asqueella

Using a hypen makes sense punctuation- and pronouncation-wise, as it's historically a compound word, and the standalone single-letter abbrevitation "e" is confusing, so the "right thing" would be to use the "e-mail" form. However, there's also no ambiguity in using "email", so both of them are valid choices. KB should simply chose one for the style to be consistent. I myself would go with the hypenated form, because "email" reminds me of things like writing "ur" instead of "your" or "sum" instead of "some" etc. Wikipedia also uses "e-mail".

― Fatalis 12:33, 25 Mar 2005 (PST)

Formatting of technical terms

"Backup" is a noun, and "back up" is a verb. You don't "backup" your files; you "back up" your files. Please add this to the Pet Peeves section of the Style guidelines. --wintogreen

Go ahead and add it. I don't see a "pet peeves" section :) --asqueella