From AlfrescoWiki

This page provides the guidelines for writing and editing in the Alfresco Wiki. The guidelines include recommendations for using wiki markup and general writing standards. These guidelines are based on information in Wikipedia's "How to edit a page" but are shortened and are more specific for Alfresco. This page also includes some instructions for general Wiki tasks and monitoring.

It is intended for anyone who is writing or editing in the Alfresco Wiki to help maintain consistency and quality across all information. Note also that the Technical Documentation team use these guidelines as the standard for copy editing all Alfresco wiki pages.

The Alfresco Wiki main page is at http://wiki.alfresco.com/wiki/Main_Page. The main page shows information about Alfresco, including news and events, and links to useful pages from several navigation bars. The left navigation bar shows a set of static links to useful pages and you cannot edit these links. You can edit all other areas and navigation links.

Contents 1 Wiki markup 1.1 Formatting buttons 1.2 Basic formatting 1.3 Headings 2 Example heading 1 2.1 Example heading 2 2.1.1 Example heading 3 2.1.1.1 Example heading 4 2.2 Lists 2.3 Links 2.4 Images 2.5 Tables 3 Writing and editing guidelines 3.1 Space before full stop 3.2 Titles 3.3 Contractions (e.g. and i.e.) 3.4 Ellipses (…) 3.5 Example code 3.6 Code in a sentence 3.7 Lists of properties 3.8 Numbered lists 4 Writing and editing in the Alfresco Wiki 4.1 Edit a page 4.2 Preview a page 4.3 Save a page 4.4 Using categories 4.5 Using templates 4.6 Permitted HTML

[edit] Wiki markup

The wiki markup is the syntax you use to structure and format a wiki page.

For a complete guide to all the available wiki markp up, see MediaWiki Formatting or Wikipedia's How to edit a page. For quick reference of the wiki markup and other actions, see the WikiMedia Reference Card.

This section provides a summary of commonly used mark up.

[edit] Formatting buttons

The formatting buttons are at the top of the edit box. You can highlight a word and then click a button to apply to wiki mark up around that word.

[edit] Basic formatting

Italic text: use ''text'' to display text

Bold text: use '''text''' to display text

Bold and italic text: use '''''text''''' to display text

Colored text: use <font color=red>text</font> to display text

[edit] Headings

Level 1 head: use =Example heading 1= to display:

[edit] Example heading 1

Level 2 head: use ==Example heading 2== to display:

[edit] Example heading 2

Level 3 head: use ===Example heading 3=== to display:

[edit] Example heading 3

Level 4 head: use ====Example heading 4==== to display:

[edit] Example heading 4

A Table of Contents will automatically be generated when four headings are added to an article.

Always follow a heading with an introductory sentence.

[edit] Lists

Bulleted list: use *text to display:

• text

2nd-level item: use **text for indented items

• text
  • text
  • text
• text

Numbered list: use #text to display:

1. text

2nd-level item (indented): use ##text for indented items

1. text
2. text
   1. text 2
   2. text 2

[edit] Links

Internal link: use [[Page name]] to display Page name

Internal link with different display text: use [[name of page|display text]] to display display text

External link: use [http://www.alfresco.com] to display [1]

External link with no display text: use http://www.alfresco.com to display http://www.alfresco.com

Email link: RecipientName -or- EmailAddress (place space between email address and display text)

[edit] Images

Image below this text: Use [[Image: alfresco_icon.jpg]] to display:

Image with alternate text: Use [[Image:alfresco_icon.jpg|this is alternate text]] to display:

Image aligned right with caption text: Use [[Image:alfresco_icon.jpg|frame|Caption text]] to display:

[edit] Tables

For more information on creating tables, see http://meta.wikimedia.org/wiki/Help:Table.

The following mark up generates a basic table (for 2 columns, 1 title row, 4 rows).

{| border="3" cellpadding="2"
!example title 1!!example title 2
|-
|width="200"|example||width="200"|example
|-
|example||example
|-
|example||example
|-
|example||example
|}

example title 1	example title 2
example	example
example	example
example	example
example	example

[edit] Writing and editing guidelines

Use the following guidelines when writing and editing in the wiki.

[edit] Space before full stop

Use only one space after a full stop.

[edit] Titles

Use sentence case for all titles rather than title case.

Replace: Creating New Workflows

With: Creating new workflows

Always follow a title with an introductory sentence.

[edit] Contractions (e.g. and i.e.)

Replace all contraction with full wording:

• i.e. roughly translates to "that is" or "in other words"
• e.g. roughly translates to "for example"

Replace: e.g.

With: for example

Replace: i.e.

With: that is

[edit] Ellipses (…)

Remove all ellipses unless used within code or examples.

[edit] Example code

Place example code within preformatted text. To create the preformatted text, add a space at the beginning of the line.

Preformatted looks like this:

<webscript>
  <shortname>Blog Search</shortname>
  <description>Find all blog entries whose content contains the specified search term</description>
  <url>/sample/blog/search?q={searchTerm}</url>
  <url>/sample/blog/search.atom?q={searchTerm}</url>
  <url>/sample/b/s?q={searchTerm}</url>
  <url>/sample/b/s.atom?q={searchTerm}</url>
  <format default="html">extension</format>
  <authentication>guest</authentication>
  <transaction>required</transaction>
</webscript>

[edit] Code in a sentence

Use the <tt> tag for all code within a sentence. Use the <tt> tag for names of file and path names, commands, output, code, and text that the user types.

[edit] Lists of properties

Use a definition list for lists of properties. This ensures that the property name is not confused with other text or symbols. For example:

property

description

title

is the title of the chrome

renderer-type

is the ID of the renderer

[edit] Numbered lists

Use the hash (#) for creating a numbered list. For example, the following wiki mark up:

# This is the first step.
# This is the second step.
# This is the third step.

Will generate this output:

1. This is the first step.
2. This is the second step.
3. This is the third step.

If you add a new line between one of the steps, this causes the numbering to restart. For example, the following wiki mark up:

# Open a editor.
# Enter the following text:

Hello World

# Save the file.

will generate the following output:

1. Open a editor.
2. Enter the following text:

Hello World

1. Save the file.

To restart the numbering for step 3, use the HTML <ol start=num> tag. For example:

# Open an editor.
# Enter the following text:

Hello World

<ol start=3> 
<li>Save the file.
</ol>

will generate the following output:

1. Open an editor.
2. Enter the following text:

Hello World

3. Save the file.

[edit] Writing and editing in the Alfresco Wiki

This section describes how to edit, preview, and save a page.

Every page has a number of tabs and links:

Article	The current page. Use this tab to get back to the page.
Discussions	The page you use to discuss this article. Note that most of these are red to indicate that this is a new page.
Edit	Click this tab to edit the page.
History	Displays the edit history of the page, including when and who editing the page. It also displays the edit summary.
Move	Click this tab to rename the page.
Watch	Click this tab to add this page to your watch list.

[edit] Edit a page

There are two ways you can edit a page:

• To edit the whole page, click the Edit tab at the top of the page.
• To edit only one section at a time, click the edit link next to the section title.

The edit box opens, which is a mixture of a WYSYWIG editor and a text editor.

Note the formatting buttons at the top of the edit box. You can highlight a word and then click a button to apply to wiki mark up around that word.

Text that you enter is formatted in paragraphs. All carriage returns are interpreted as the end of the paragraph and therefore also the end of the markup tag.

Some of the common markup tags are:

• Headings are marked up with equal signs
• Bullet lists are marked up with asterisks
• Numbered lists are marked up with hashes
• Definition lists are marked up with semi colons (term) and colons (definition)

[edit] Preview a page

When you have made some changes to a page, you can preview the page before you save it. Preview is useful for checking that you have entered the mark up correctly and it is displaying as expected. It is also a more convenient way of proof reading the text.

To preview the page, click Show preview. The previewed page appears below the edit box.

[edit] Save a page

When you want to save the page, enter a brief note in the Summary box about what you changed. If you have made only minor changes to the page, check the This is a minor edit checkbox. The Summary and the minor edit information appear in the edit history.

To save the page, click Save page.

Alternatively, if you do not wish to apply the changes, click Cancel.

Note that for concurrent editing, that is, when two people start to edit the page at the same time, you may not have your changes applied to the page.

The second person (and later persons) to save the page receives an Edit conflict message. It is also possible to merge the changes into the current version. The wiki also checks for a conflict if you are editing and do a preview of the edit.

[edit] Using categories

Categories are a way of organizing and grouping related wiki pages. Anyone can add categories to a page, including using exiting categories or creating new ones.

To add a category to a page, enter the following text at either the beginning or the end of the page:

[[Category:<category name>]]

This creates a link to the main page of that category.

Note: if you are creating a new category, when you save the page, the link will be red. This indicates that there is currently no category main page. Click on the red category link and enter a short description of the category in the edit box. When you save the page, the main page for the category is created. So see this category, and all other categories, click the Browse Categories link from the main

You can enter multiple categories for each page. For example, the following mark up adds the categories to the current page: [[Category:Linux]][[Category:installation]][[Category:2.2]]

[edit] Using templates

A template is a page that has a name with a Template: prefix. For example, Template:API_Reference_Template, where API_Reference_Template is the template name.

To use a template, add the following template tag to a new page:

{{subst:template name}}

The template tag comprises two instances of the brace at either side of the template page name, excluding the Template: prefix. For example, to use Template:API_Reference_Template, use the following tag:

{{subst:API_Reference_Template}}

When you save the page, the template tag includes a copy of the content of the template in your current page, which you can then edit.

[edit] Permitted HTML

In addition to wiki mark up, the following HTML elements are permitted:

<b> <big> <blockquote> <br> <caption> <center> <cite> <code> <dd> <del> <div> <dl> <dt> <em> <font> <h1>

<h2> <h3> <h4> <h5> <h6> <hr> <i> <ins> <li> <ol> <p> <pre> <rb> <rp> <rt> <ruby>

<s> <small> <span> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul> <var> <!-- ... -->