When we edit articles, we try to make sure the style and formatting is consistent. The following are some rules we use (and we'd appreciate if you'd use as well):
- The inline wiki link style is of the form [[URL|description]], where the URL is on the left side of the vertical bar and the description is on the right.
- ZENPRESS recognizes the wiki inline link style. Use the wiki link style for most cases, unless specifically highlighting a URL, for example, in a site of the month article. If highlighting a URL, it should be a short URL.
- In the Product Availability and Resources section, links should be in the form of imperative sentences. For example "Read the article." In this case, "article" would have an inline link.
- Put titles of full works (books and magazines) in italics. Put titles of articles or chapters in quotes. Put titles of software products in plain text. While, technically, it might be appropriate to also put full-work software products in italics, this is not common practice. Put full song album titles in italics; titles of individual songs in quotes.
- Always use a comma before "and" and "or" in a list (e.g., computer, monitor, and keyboard).
- When using "e.g.," which means "for example," always format it as e.g., (e-dot-g-dot-comma).
- Always replace "user" with you. This changes the feel of articles.
- Always write in first person, not third person.
- Substitute "I" in a set of steps with "you." The article will feel much more personal to the reader.
- Don't be stiff in writing.
- Don't use punctuation in state names and don't spell them out. Format them like CA, NJ, DC, etc.
- Never use the word "click" to describe a menu item. Use "select" instead. For example, say "Select Open from the File menu." However, you can say "click," as in "Click the Post Changes button," when talking about clicking a button.
- Always refer to Palm stuff as Palm devices or Palm computing devices (rather than "Palms" or "PalmPilots," unless you're specifically talking about a PalmPilot model). We have trademark licenses with Palm Computing that dictates our use of their terminology.
- Likewise, always refer to "CE" anything as "Windows CE anything." Never use "CE" alone. This is per our contract with Microsoft.
- No space between .SUMMARY, .AUTHOR and first paragraph. (This refers to the dot commands we use in our journal production system.)
- Always use two dashes with no spaces (not an emdash) as in: the computer--the monitor...
- When an acronym or buzz word comes up, follow up the word with the definition. For example: When hooking up the SCSI (i.e., Small Computer Systems Interface) device...
- Use contractions. This keeps articles lighter and less formal than spelling out words.
- There should be a period after each product in the product availability section and a blank line between each product.
- If you don't know a word, always try to replace it with one you do know.
- We identify articles during our edit process by a single keyword. This is the dot command .KEYWORD, located at the very top of an article. The keyword in the article is one word that the article and all the figures can be named by (eg.,--clipbook, pqa, etc.) It must be exactly one word without punctuation, and it must be lower case.
- Always end a Web site name in the Product Availability section with a period.
- There should never be a heading at the very beginning of an article immediately following the author. Always begin articles with a paragraph or more.
- Don't break up a list with a figure.
- When refering to a URL in parens, we can't have an open parenthesis immediately before the URL; do it like this: (see http://...), not (http://...)
- When using titles and headers, be sure the first letter is capitalized, then all the rest are lower case.
- Always bullet lists. Bullets should go * (space) then first word.
- Always introduce a bulleted list with a sentence or more. Don't just drop bullets right after a header.
- If a diagram is included, please make sure it will image well as a GIF image.
- Remember, we won't use logos or self-promotions of authors or authors' companies in articles. We will include author information in the bio (within reason).
- Don't use boldface or italics.
- Divide articles into bite-size chunks using section headers. You can go two levels deep into section headers, but don't get carried away.
- Turn off smart quotes and other typographic tools (like bullets done by typing option-8). Include no special formatting. All formatting should be done by means of rules and commands to work with our ZENPRESS editorial production system.
- Make sure authors include biographies at the end of their articles. Bios should usually be very short, about 10 words or so, of the form "Joe Schmoe is Senior Engineer for Widget, Inc. He can be reached at jschmoe@widgets.com." If the author has a particularly relevant history with the topic of the journal, feel free to include it--if space is available, always try to include a Web page address.
- Capitalize DOS file names (short ones).
- Captions always need to be full sentences and should be short (less than ten words).
- Always check spacing. Never have double-spaces.
- Do not embed illustrations or screenshots in the articles. Instead, keep them as separate external files. Name images Figure A, B, etc.
- Don't put a "/" between Notes and Domino; it should be Lotus and Domino, not Notes/Domino
- Must put at very beginning of http: address (mode) in code or ZENPRESS will read it as an address and try to go there.
- Always doublecheck figures. Make sure large and small figures match, figures match article and caption matches figure and article.
- Always doublecheck all Web addresses. Make sure they open something and that address is relevant to article.
- Words such as Anonymous, Reader, Depositor, Administrator, Default, etc. are usually capitalized, but you should check out usage. If word is proper name, definitely capitalize. If not a proper name, this becomes editors' discretion.
- Capitalize computer terms such as True/False, OK, selections from menu bars, etc.
|
|
