[wsdm][Editor] General Writing Guidelines

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.