[wsdm][Editor] General Writing Guidelines

["Andreas Dharmawan" <andreas@westbridgetech.com>]

Title: Message

Hi Team:

 

I put together the following writing guidelines. I have applied the guidelines to Chapter 1 and 2 of MUWS Spec. In the coming days, I will apply the guidelines to the remaining of the document.

 

Please review the guidelines and provide feedback. I am happy to incorporate best practices.

 

Thanks

 

General writing guidelines

 

• Avoid excessively long paragraphs. Good guideline = approx. 4-5 print/display lines per paragraph, depending on ability to split up paragraph logically.
• Format “Normal” paragraphs to generate 6pt spacing above and below each paragraph (already formatted in this spec).
• Figures:

°         In a large document, all figures should be captioned, and the caption centered either above or below the figure.

-  When deciding whether to place captions above or below figures, you must be consistent throughout the entire document.

°         In a doc with numerous figures, each figure should be numbered (such as, Figure 2-1, …)

°         Numbered figures should be referenced in some way (such as, “Figure n illustrates …”) before the figure appears in the text flow.

°         Figure references should always be “forward” references; backward references (to a previously-displayed figure) are ideally only to the most recently displayed figure. Otherwise, it may be better to repeat the graphic as a new figure.

• Try to avoid use of apostrophe to form possessive nouns – it is difficult to read for some people. In other words, instead of “…the resource’s functional interfaces…” write “...the functional interfaces for the resource…” [Note: “for” may change dependending on the phrase].
• Conventional practices:

Instead of …	Write this…
i.e., …	that is, … or in other words, …
e.g., …	for example, … or such as, …
…, etc.	…, and so on.

 

• Bullets:

°         If three or more items are to be listed in a sentence, list them as bullet items.

°         Bulleted lists should be numbered only if they represent a sequence of actions that must be performed in a specific order. When numbered, they are considered numbered lists, rather than bulleted list. See discussion on numbered lists later in this guide

°         When writing a bulleted list, each item in the list should be:

-  Capitalized the same

-  Full sentences, or discrete phrases

-  End in periods, or not

°         If a bulleted list breaks across a page boundary, I find it’s good to prevent “orphaned” list items of less than three items. In other words, ensure that at least three list items appear before and after the page break. If not, then keep the lines of the bulleted list together on the next page.

• Remember the commas after introductory clauses:

°         “When …, …”

°         “In …, …”

°         “Because …, …”

• Numbered lists:

°         Used only for sequential listing of items, where relative order is significant

°         Each item should represent a single physical step or concept.