Skip to main content

Confluence Wiki Standards and Guidelines

About​

Documentation Team: Please observe these standards and guidelines when editing Confluence wiki pages to maintain a consistent user experience.

Copy the page excluding the wiki generated table of contents and paste it directly into a new Confluence page based on the FS template.

Then update the record for the page on Move Tracker spreadsheet that was set up by Belaid Areski selecting "Moved" if that's all you did, "Editing" if you now own the page and will correct links, grammar, and factual errors, "Complete" if the page requires no further editing.

This will indicate to other members of the Docs Team who is editing the page and whom to contact if you wish to update it instead. Note that some old wiki pages will not be moved because they are old and outdated or no longer apply to the current version of FreeSWITCH; these pages are marked "Deleted" and there are quite a number of them. Links that were redirected to the ultimate page on the old wiki can be marked as "Duplicate" as the spreadsheet was built by a script that did not differentiate between live pages and redirected links.

xxx

Click here to expand ToC

Structure​

Use the "FS template" when you create a new page that has all the macros that contain the Table of Contents with all formatting ready to go.

There is also a macro {ft that inserts the FreeSWITCH Table of Contents by itself at the location on the page where you type the macro.

Each page shall start with the heading 1 named "About" followed by a brief narrative explaining the topic of the page.

Next, if the page is long enough to warrant a Table of Contents, insert the {FS ToC macro which consists of the Expand macro containing a Panel macro containing a Table of Contents macro. (The FS ToC macro is finicky and sometimes reports an error, then it works later.) Don't copy the ToC from the old wiki.

After that comes whatever commands, variables, narrative, diagrams, tables, and code examples appropriate to explain the topic of the page.

Don't forget to add labels to the page. Use plural words for everything other than proper terms used in FreeSWITCH, such as "variables", "modules", etc. Exceptions include "dialplan" and "directory" since these proper names are used internally to FS.

Typical Confluence Page Structure

About​

This is the About text.

Table of Contents macro goes here (see Shortcuts)

Heading 1​

First major paragraph.

Heading 2​

Text under heading 2

Another Heading 2​

Other text under next heading 2

Heading 3​

Text

Another Heading 3​

Text

Another Heading 1​

Second major paragraph.

(Don't forget to add appropriate labels to the page from the existing list in use.)

BNF Formatting​

Commands are expressed using Backus–Naur Form as outlined in the table below.

literala literal argument
<variable>a variable argument
[optional]an optional argument
|symbol for or
&symbol for and
*wildcard character
...symbol for repetition
?single character wildcard
(grouping)override precedence

Command Format​

Command name

Brief description of command.

Usage, styled as Preformatted text (shortcut = Ctrl+7), beginning with the string "Usage:"

Listing of arguments and their meaning, one per line

Notes, warnings, additional explanation as necessary.

Example of command 'alias'

alias​

A means to save some keystrokes on commonly used commands.

Usage: alias add | stickyadd <alias> <command> | del <alias> | *

add - add an alias
stickyadd - add an alias which persists across restarts
<alias> - the user defined name for the new command
<command> - the original command name

Examples:

alias add reloadall reloadacl reloadxml
alias add unreg sofia profile internal flush_inbound_reg
alias stickyadd reloadall reloadacl reloadxml
alias del reloadall

Only really works from the console, not fs_cli.

Paths​

conf/ in the docs represents the generalized location of the FreeSWITCH™ parent configuration directory. Linux packages place config files under /etc/freeswitch while compiling from source typically locates them under the /usr/local/freeswitch/conf tree. Windows clearly uses a different location. Don't use hard-coded paths to the configuration files if possible.

Styling​

Confluence standardizes the look and feel of pages by providing only styles in the upper left listbox, rather than random markup. Regardless of the heading levels copied over from the MediaWiki site, please use the following conventions to maintain consistency here in Confluence:

This Is Heading 1 for top-level headings throughout the page​

This Is Heading 2 as a sub-section under Heading 1​

This Is Heading 3 as a sub-section under Heading 2​

...and so on. These not only style the text visually, they also provide semantic hints to screen readers for those with vision impairment. The {fs ToC macro only includes h1 through h3 to keep it manageable on big pages.

Please do not use boldface and italics except where they are appropriate. Let the style sheet do its job:

  1. Paste or type the new text first
  2. Style the text (see Shortcut keys)

Random text styles circumvent these useful goals, plus they can be used to excess and dilute the emphasis. Use the tip, info, note, and warning macro boxes to set out text in place of their wiki equivalents.

It can clarify a sentence to mark commands and log output that appear inline with the monospace style on the toolbar button in the upper left that looks like a capital A with a long crossbar and small superscript lower case a to the left of it. AFAIK there is no keyboard shortcut for this style.

Shortcuts​

No need to use the mouse and menu if you want to keep your fingers typing on the keyboard.

Type thisto display this
h1.<space>Heading 1 format
h2.<space>Heading 2 format
{codeFS code block pre-formatted
{fsFreeSWITCH™
{ftFS Table of Contents package pre-formatted
{tipPanel with green check mark in title
{infoPanel with blue circumscribed i in title
{notePanel with bang ! in yellow triangle

Editing

Use great care in the Confluence editor when cutting a block of text or typing Backspace at the beginning of a line that has special formatting. There is hidden formatting that will be deleted in this operation (at least in Firefox) that will return the current line to standard Paragraph formatting. Use Ctrl-Z to undo and carefully try again.

Callout Graphic Annotation Mapping​

Confluence provides macros that insert a div box that contains text and graphics and highlights it with an icon similar to MediaWiki.

Code Block​

To show multiple lines of code, use the Confluence 'code' macro. Use to enclose blocks of XML, HTML, C, bash scripts, and other code that is best displayed using the pre-formatted monospace style. Whatever goes inside the code block will automatically be styled with the Preformatted style. I set the system-wide default to highlight XML syntax and use the Emacs theme, so you can leave the default settings (blanks) unless there is a good reason to choose different syntax highlighting.

Depending on whether it is a bash script or source code, choose the appropriate language, type a short title; check the 'Collapse' box if it is many lines of code to avoid filling up the page needlessly. In many cases the syntax highlighting will reduce legibility, so just leave it at the default of blank, no syntax highlighting. Use your best judgment.

MediaWiki code and icon:

{{keyboard|content=Code block.}}

Code Block

Menu: Insert > Other Macros > Code Block
Keyboard shortcut: {code

Tip Block​

Callout that draws attention to a time-saving tip or additional information that deserves the special attention of the reader.

Menu: Insert > Other Macros > Formatting > Tip

Keyboard shortcut: {tip

Info Block​

Callout that provides links and pointers to additional information on the topic.

MediaWiki code and icon:

{{info|content=Info text.}}

Menu: Insert > Other Macros > Formatting > Info

Keyboard shortcut: {info

Note Block​

Callout that draws attention to important information about the topic.

MediaWiki code and icon:

{{warning|content=Warning text.}}

Menu: Insert > Other Macros > Formatting > Note

Keyboard shortcut: {note

Warning Block​

Callout that demands attention to critical information that could cause data loss, damage, or fraud if ignored.

MediaWiki code and icon:

{{error|content=Warning text.}}

Menu: Insert > Other Macros > Formatting > Warning

Keyboard shortcut: {warn

When there is a warning for a specific command always add the warning before the code block to grab the attention of the reader.

x

Confluence YouTube Tutorial​

UML Diagrams​

Activity Diagrams​

The PlantUML add-on is installed to allow text source to be rendered as UML activity diagrams. These can be used to illustrate call flow. Help for activity diagrams is available from the author's web site.

Sequence Diagrams​

The add-on also supports sequence diagrams which are useful for illustrating SIP message flow. Help for sequence diagrams is available from the author's web site.

00000000 40 73 74 61 72 74 75 6D 6C 0A 3D 3D 20 49 4E 49 @startuml.== INI 00000010 54 49 41 4C 49 5A 41 54 49 4F 4E 20 3D 3D 0A 41 TIALIZATION ==.A 00000020 6C 69 63 65 20 2D 3E 20 46 53 3A 20 49 4E 56 49 lice -> FS: INVI 00000030 54 45 0A 46 53 20 2D 3E 20 41 6C 69 63 65 3A 20 TE.FS -> Alice: 00000040 31 30 30 20 54 72 79 69 6E 67 0A 46 53 20 2D 3E 100 Trying.FS -> 00000050 20 42 6F 62 3A 20 49 4E 56 49 54 45 0A 42 6F 62 Bob: INVITE.Bob 00000060 20 2D 3E 20 46 53 3A 20 31 38 30 20 52 69 6E 67 -> FS: 180 Ring 00000070 69 6E 67 0A 46 53 20 2D 3E 20 41 6C 69 63 65 3A ing.FS -> Alice: 00000080 20 31 38 30 20 52 69 6E 67 69 6E 67 0A 42 6F 62 180 Ringing.Bob 00000090 20 2D 3E 20 46 53 3A 20 32 30 30 20 4F 4B 0A 46 -> FS: 200 OK.F 000000A0 53 20 2D 3E 20 41 6C 69 63 65 3A 20 32 30 30 20 S -> Alice: 200 000000B0 4F 4B 0A 41 6C 69 63 65 20 2D 3E 20 42 6F 62 3A OK.Alice -> Bob: 000000C0 20 41 43 4B 0A 3D 3D 20 52 45 50 45 54 49 54 49 ACK.== REPETITI 000000D0 4F 4E 20 3D 3D 0A 41 6C 69 63 65 20 2D 5B 23 62 ON ==.Alice -[#b 000000E0 6C 75 65 5D 3E 20 42 6F 62 3A 20 52 54 50 20 6D lue]> Bob: RTP m 000000F0 65 64 69 61 20 73 74 72 65 61 6D 0A 42 6F 62 20 edia stream.Bob 00000100 2D 5B 23 62 6C 75 65 5D 3E 20 41 6C 69 63 65 3A -[#blue]> Alice: 00000110 20 52 54 50 20 6D 65 64 69 61 20 73 74 72 65 61 RTP media strea 00000120 6D 0A 46 53 20 2D 3E 20 41 6C 69 63 65 3A 20 55 m.FS -> Alice: U 00000130 70 64 61 74 65 20 53 44 50 0A 46 53 20 2D 3E 20 pdate SDP.FS -> 00000140 42 6F 62 3A 20 55 70 64 61 74 65 20 53 44 50 0A Bob: Update SDP. 00000150 3D 3D 20 54 45 52 4D 49 4E 41 54 49 4F 4E 20 3D == TERMINATION = 00000160 3D 0A 42 6F 62 20 2D 3E 20 41 6C 69 63 65 3A 20 =.Bob -> Alice: 00000170 42 59 45 0A 41 6C 69 63 65 20 2D 3E 20 42 6F 62 BYE.Alice -> Bob 00000180 3A 20 32 30 30 20 4F 4B 0A 40 65 6E 64 75 6D 6C : 200 OK.@enduml 00000190 0A .

Labels​

Labels tie together related pages. Please don't create a new label if you can find an existing label.

On any Confluence page an editor can type L (the letter "ELL") to bring up the Label dialog box. Typing a few characters starts an incremental search of existing labels.

Plural labels suggest a group and are preferred; e.g. "operating-systems", "clients", "developers", etc.

  1. A-B
  2. C
  3. D
  4. E-F
  5. G-H
  6. I-K
  7. L
  8. M-N
  9. O-Q
  10. R
  1. S
  1. T-V
  1. W-Z
  1. 0-9

Hints and Tips​

  1. FreeSWITCH™. You do not have to use the trademark symbol every time. It appears in every instance on the top level page so hopefully that should drive the point home. If you use it once in the About section of a new page that should be sufficient. In many cases the old wiki used the abbreviation FS to represent FreeSWITCH which should be acceptable as long as it is clear what is meant; just make sure it can't be conflated with "file server".
  2. Sometimes for no particular reason when editing pages (in Firefox) the cursor focus moves to the top or bottom of the page. Very annoying especially when editing large pages. Although Atlassian touts Confluence as a "reliable editor" it has this and other quirks, so be careful when editing text. It sometimes does things that you do not expect.
  3. When Confluence appears to have old entries on the main page under "Recently Updated Pages" an admin needs to flush the cache and go check the Content Indexing administrative pages.

ToDo​

  • Copy remaining pages from MediaWiki to Confluence
  • Create a reference/sample page that contains all of the formatting elements for a page.
  • Find a way to have "Notify Watchers" in edit screen unchecked by default. A: Checkbox remembers its state, so clear it and forget it
  • See if we can set the ToC list style to "none" by default because a bulleted ToC is fugly
  • Decrease the default ToC Heading Indent to something a little more visually pleasing like 12px (or better still 1ex)
  • Change the ToC template to shade and put a box around like MediaWiki does it so that it "pops" a little better

Attachments:​

index.png (image/png)
info.png (image/png)
warning.png (image/png)
ToC-Readability.png (image/png)
ToC-Readability.png (image/png)
ToC-Readability.png (image/png)

Comments:​

What about adding to the Guideline some rules for code snippet. I met 3 problems so far:Not using the code macro, so the code is not display nicely.Respect an indentation between code snippet, some have 2 spaces, some 3 spaces and other 4. I would recommend 4 spaces for indentation.Comments in code and the variables name shall be in English. I translated earlier a Spanish code examples, which was obviously not appropriate for everyone. Posted by areski at Jun 12, 2014 12:33
heading indent = 1exThis seems very little Posted by areski at Jun 12, 2014 12:46
1ex is very little. I chose that in response to a comment that the default indent is excessive. If the indent is obvious to the reader, then that is all I hope for. Unfortunately, each Table of Contents macro must be changed from the default manually, individually so if there is to be a change it is best to make it now before we have many pages with undesired values for the indent.It might be possible to change the default, but that must be done by SwK or other super admin in the Confluence file system. Posted by boteman at Jun 12, 2014 12:57
I 'm quite convinced that with the current ToC we are losing readability, especially if we compare to the previous approach on wiki,here to compare:Please find here a ToC using number list and 2ex for indent -> Get Started with Confluence Docs Posted by areski at Jun 19, 2014 14:30
OK, I modified the {ft macro to include the "outline" parameter which is the Confluence way of enumerating ToC entries.As I encounter pages that have the old ToC definition I will delete it and drop in place the {ft macro which does it all. Posted by boteman at Jun 23, 2014 04:13