• Diff for "StyleGuidelines"
  • Immutable Page
  • Info
  • Attachments
Differences between revisions 2 and 3
Revision 2 as of 2007-09-01 10:03:56
Size: 5044
Editor: CPE-58-161-160-149
Comment: Add 'If you aren't sure'
Revision 3 as of 2007-09-01 10:04:26
Size: 5046
Editor: CPE-58-161-160-149
Comment: Typo Fix
Deletions are marked like this. Additions are marked like this.
Line 61: Line 61:
If you aren't sure about something, have a look on [http://gitweb.opencompositing.org/ Gitweb], read the item's source code's comments. If you still aren't sure, ask on the [:Join_our_community:mailing list, IRC or the forums] If you aren't sure about something, have a look on [http://gitweb.opencompositing.org/ Gitweb] or read the item's source code's comments. If you still aren't sure, ask on the [:Join_our_community:mailing list, IRC or the forums]

This page will contain a set of general guidelines which should be observed when composing and posting documentation to the Compiz Fusion wiki.



Mechanics of prose

The mechanics of prose are the technical aspects of writing. These are things like grammar, spelling, punctuation, structure and diction. Not all writers are experts in this department, nor do they need to be; however, using the correct tools for the job will help ensure that you communicate your ideas effectively. You do not need to be a native speaker of English.

To make a long lesson short: please proofread what you write before posting it. Use a spelling checker if possible. It does not need to be perfect; a wiki is a collaborative project, so if you do make some errors, a fellow editor may find them and fix them for you. However, this is no excuse for you to post haphazard, unrefined work and expect other people to make sense of it. If you have the time to post it, you also have the time to proofread it.

(!) Things to consider: Does my writing say exactly what I want it to say? Have I made my statements clear and unambiguous? Could my statements be misunderstood in any way? Have I taken the time to check for careless errors?

Tone, voice, and audience

The tone is the way in which you address the reader. Choosing a tone means making assumptions about the reader. These assumptions may be about their beliefs, their desires, or their experiences, among other things. For example, you might assume that the reader has never heard of Linux. Or, you might assume that the reader wants to know which branch of the Git repository to checkout.

The voice is expressive of the persona which you, as the author, display to the reader. Choosing a voice means assuming a certain role, position or personality. For informational pages, the voice should be semi-formal, impersonal, and objective. (Think of technical manuals.) Since this is a collaborative wiki, there should be no mention of "I", "me", "my", etc., unless you are writing an explicitly personal page. Also, be careful when making statements with "we", "us" or "our".

If you're writing for someone other than yourself, then the audience is obviously of very high (if not highest) importance. This is the entity that will read what you write. If you know your audience, then the tone and voice will logically follow.

These three factors are shaped by the ultimate purpose of your writing. Your purpose should be clear before you begin writing.

(!) Things to consider: What do you seek to accomplish with your writing, in terms of tone, voice and audience? Do you write in a style which is appropriate for your purpose?

Formatting standards and consistency

Plugin names and application names are always bolded.

  • (!) The [:Plugins/Animation:Animation] plugin can be configured via ["CCSM"].

Titles and names of sections, such as tabs and panels, are always italicised.

  • (!) You can adjust effect-specific settings under the Effect Settings tab.

Menu names are italicised. This includes submenus, but the final destination in a chain of menus (ie. the item which is selected and which causes the menu to close) is bolded.

  • (!) To launch ["CCSM"] from the GNOME menu, navigate to System -> Preferences -> CompizConfig Settings Manager.

Keyboard shortcuts are written as they appear in ["CCSM"], and they are formatted as code.

  • (!) The default keyboard binding to initiate [:Plugins/Expo:Expo] is <Super>E.

Terminal commands are also formatted as code (without quotation marks around it). If they are at the end of a sentence, omit the period (to prevent it from being misinterpreted as part of the command).

  • (!) If the window decorator has crashed or has not been launched automatically, it can be manually started with emerald --replace &



(!) Things to consider: Why should my content be placed on this page? What is the purpose of the page? Is there a better place for my content?


(!) Things to consider: What information does the reader obtain by reading my content? Would the reader run into problems if this information were not available? Is the same information already presented elsewhere? (If so, what are my reasons for repeating it here?)


(!) Things to consider: Have I verified that my statements are all 100% true? Am I using the correct names/terminology to refer to things?

If you aren't sure about something, have a look on [http://gitweb.opencompositing.org/ Gitweb] or read the item's source code's comments. If you still aren't sure, ask on the [:Join_our_community:mailing list, IRC or the forums]

StyleGuidelines (last edited 2008-03-30 18:33:56 by localhost)