Revision 5 as of 2007-09-02 23:33:22

Clear message
  • 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.

TableOfContents(3)

Presentation

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 monospace.

  • (!) 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 &

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?

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:

  • [http://gitweb.compiz-fusion.org/ Gitweb]

  • the [:Join_our_community:mailing list, IRC or the forums]
  • the source code (especially if it contains comments by the author)

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