In-house style: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
mNo edit summary
(→‎Pages: Rules want us to call Mozilla "Mozilla Suite, not Mozilla, Suite, Seamonkey, or any other name.")
Line 6: Line 6:
* Stop using the category format (such as "Firefox : FAQs : Topic") when naming new pages, since it's been in the Rules for a while now. Change to general topic names like "Help old ladies across the street" with an optional "(Firefox)" at the end if it only applies to Firefox, etc.
* Stop using the category format (such as "Firefox : FAQs : Topic") when naming new pages, since it's been in the Rules for a while now. Change to general topic names like "Help old ladies across the street" with an optional "(Firefox)" at the end if it only applies to Firefox, etc.
* Use the imperative in the topic title. By this, I mean use "Help old ladies" instead of "Helping old ladies" or "Helped old ladies" or "Have helped old ladies".
* Use the imperative in the topic title. By this, I mean use "Help old ladies" instead of "Helping old ladies" or "Helped old ladies" or "Have helped old ladies".
* If the article applies to Mozilla and Firefox/Thunderbird, create it and edit it for Mozilla and Firefox/Thunderbird. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to Mozilla too. This is a shame, because Mozilla is in need of more people creating resources for it and converting old content to it.
* If the article applies to Mozilla Suite and Firefox/Thunderbird, create it and edit it for Mozilla Suite and Firefox/Thunderbird. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to Mozilla Suite too. This is a shame, because Mozilla Suite is in need of more people creating resources for it and converting old content to it.


===Punctuation===
===Punctuation===

Revision as of 09:35, 24 February 2005

This is just going to be a list of stylistic writing suggestions that can make this entire KB more consistent in writing for now, in an informal bullet form. Feel free to add or delete any changes, since I border on grammar nazi. --hao2lian

Discuss these conventions on the discussion page! --Mozcerize

Pages

  • Stop using the category format (such as "Firefox : FAQs : Topic") when naming new pages, since it's been in the Rules for a while now. Change to general topic names like "Help old ladies across the street" with an optional "(Firefox)" at the end if it only applies to Firefox, etc.
  • Use the imperative in the topic title. By this, I mean use "Help old ladies" instead of "Helping old ladies" or "Helped old ladies" or "Have helped old ladies".
  • If the article applies to Mozilla Suite and Firefox/Thunderbird, create it and edit it for Mozilla Suite and Firefox/Thunderbird. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to Mozilla Suite too. This is a shame, because Mozilla Suite is in need of more people creating resources for it and converting old content to it.

Punctuation

  • Use arrows to denote menu order (e.g. "Tools -> Options"); the greater than sign is less connotative of moving forward than a right arrow.
  • Put menu hierarchy, keyboard shortcuts, and file names into quotation marks (e.g. "Tools -> Options", "Ctrl+PageDown", "compreg.dat").
  • Just a personal pet peeve: use the dash and hyphen correctly [1] [2]. [When using dashes and hyphens, you should not include white space around them. For example, use “9–16” and “Firefox—and Mozilla—can be used” which are achieved using “9–16” and “Firefox—and”. --Mozcerize]
  • When discussing keyboard and mouse actions: left-click, right-click etc. are hyphenated and uncapitalized; Shift, Ctrl, Alt etc. have their first letter capitalized (and only their first letter); key combinations are written using "+" so that "hold down Ctrl and press 'D'" should be written "Ctrl+D".

Style

  • Use bolding and italics only when absolutely necessary.
  • Don't start too many small, idiosyncratic paragraphs. If paragraphs are a couple of sentences that last about two lines, try and see if you can combine them into one paragraph.