• Immutable Page
  • Info
  • Attachments

This page will contain a set of general guidelines which should be observed when composing and posting documentation to the Compiz Fusion wiki. The formatting conventions are listed in the topmost section for quick reference.

Presentation

Formatting standards and consistency

The SyntaxReference page offers a comprehensive manual for the wiki's formatting syntax.

Plugin names and application names are bolded in the introductory section of their individual pages. They do not need to be bolded in every instance; it is useful to bold them if you are contrasting them with another plugin, or to make them stand out as a proper name (if you feel they would otherwise blend in with regular words). If they are mentioned on other pages, they are always bolded.

  • (!) The Animation plugin conflicts with the Minimize plugin. They cannot be simultaneously enabled in 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 monospace.

  • (!) The default keyboard binding to initiate Expo is <Super>E.

Filenames (including filepaths) are also formatted as monospace.

  • (!) These options can be specified in /etc/X11/xorg.conf.

Terminal commands are 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 &

When composing a new article for a previously undocumented plugin, consider whether the format recommended by the Plugin Template is appropriate for the information you are about to present.

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.

Please review and refine 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 your fellow editors may fix any lingering errors for you. However, this is no excuse for you to post haphazard 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.

An informational wiki prioritises clear, straightforward communication of information. Please try to avoid meaningless filler words, such as "actually", "essentially", "basically", et cetera, unless they are actually essential to the basic meaning of the statement. While these are common in spoken language, they need to be carefully pruned from written language when they serve no semantic purpose. Highly subjective terms like "really", "rather", and "somewhat" seldom have legitimate uses here.

(!) Things to consider: Does my writing say exactly what I want it to say? Have I made my statements clear and unambiguous? Could I use fewer words to convey the same amount of information? 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 Compiz Fusion, but is already a GNU/Linux user. 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?

Content

Suitability

The wiki is a source of objective information, not of speculation or subjective opinion. Please remember the scope of the Compiz Fusion wiki and consider whether or not your content belongs on a certain page (if it belongs on the wiki at all).

(!) 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?

Usefulness

The wiki is geared towards both existing and potential users and contributors. It should be supplemented by the information already available for specific distros (eg. in other wikis, manuals or guides). It is not useful to duplicate non-Compiz Fusion-specific information which is already provided by other sources; please link to those sources instead, for the benefit of readers not familiar with them.

One particular issue which you may encounter is the definition of "stating the obvious". This will vary across pages, although as a baseline, you should assume that the reader is familiar with using the applications on his/her system (eg. text editors, terminal emulators, and settings managers) to accomplish the tasks you describe. For example, individual plugin pages should not describe or mention the basic usage of CCSM, as that information should already be provided on CCSM's own page.

(!) 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?)

Accuracy

The content on the wiki should be accurate and well-supported. Vague and/or unresearched remarks are not acceptable, and detract from a page's usefulness.

The following are some potentially useful resources for verifying your work:

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

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