Zaber Wiki Editing Guidelines

Transclusion warning!!!

The Zaber Wiki makes extensive use of "transclusion" (include pages) to avoid duplicate data entry. For example, product user's manuals contain mostly the same information and are therefore made up entirely of included pages. When editing any page, be sure you understand where that information may be included and make sure that your changes are appropriate.

All pages

• Provide an edit summary: Providing an edit summary, even if the edit is minor, makes the wiki work better by quickly explaining to other users what your change was about.
• Mark minor edits: If your edit is minor, please mark it as such by checking the box beneath the summary text field. A minor edit is one that doesn't change the meaning of the text. Typos, formatting, and improved sentence structure are all minor edits.
• Article style: Avoid poor grammar or spelling, conversational language, and/or repetition of data that is presented elsewhere.
• Show URLs: Keep in mind that the end user may be looking at a printed PDF version of the content. Don't exclude them by using hyper-links without displaying the url. For example, use "... the Zaber website http://www.zaber.com" instead of "...the Zaber website.

Discussions (talk pages)

• Comments in articles: Do not include comments in articles. Use the discussion tab associated with each article.
• Sign your comments: Sign every comment you make with four tildes (~~~~). This inserts your user name and a timestamp.
• Comment thread readability:Use colons (:) to indent your comments for readability. Use horizontal lines (----) to separate topics.

User's manual pages

User's Manuals such as Manuals/T-JOY are the highest level documents. They are composed entirely of included pages. No content should be entered directly in the user's manual page. Use the edit tab at the top of the User's Manual pages to see what pages have been included to build the User's Manual. To view an included page by itself, you can copy the page name into the url field of your browser after http://www.zaber.com/wiki/. While viewing the User's Manual's page, you can also use the edit links that appear on the right rather than using the edit tab at the top of the page though this can be confusing. After clicking an edit link you will immediately be editing the included page, NOT the User's Manual page. After making any changes you will have to navigate back to the User's Manual page to see the results.

Keep in mind that any pages you edit may be included in multiple user's manuals. You can see which manuals a page is included in by clicking on "What links here" in the bottom left.

Command page order

For legibility, the command pages should be included in order of command number. Unfortunately the page names do not have the numbers in them; you simply have to check which command it goes before and after to find it's place in the list.

Command pages

User's manuals are composed entirely of included pages. The bulk of these pages are "command pages" specifying information relevant to a single instruction that a device can execute. Every time the firmware for Zaber products is updated there will, inevitably, be changes to the commands and the associated command pages for those commands. These changes, if not made according to the guidelines below, could cause problems parsing the wiki to generate Zaber software help files and PDF versions of the Zaber user's manuals.

Scope

A "command page" such as T-Series/Commands/Echo Data is likely included in multiple user's manuals for multiple products. As such a command page should specify information about a single command without reference to the product or group of products that may be implementing that command. If information relevant to a particular product needs to be included, then a separate "command addendum page" such as T-Series/Commands/Echo Data/T-Joy should be created as a subpage of the base command page. When the command is included in the user's manual, the "command addendum page" should be included immediately following the relevant "command page". For example, if you edit the user's manual Manuals/T-JOY you will notice the following entries in the command section:

{{:T-Series/Commands/Echo Data}}<br>
{{:T-Series/Commands/Echo Data/T-Joy}}<br>

Command tables

Command tables are useful as a reference, but the important information should be given in the details below the table. The number of words per cell in these tables should be reduced as much as possible. These tables are parsed and used in some Zaber software applications where lengthy text will not display well. Example:

Instruction Name	Renumber
Firmware Version	5.00 and up
Command Number	2
Command Type	Command
Command Data	New Number
Reply Data	Device Id
Persistence	Non-Volatile

Uppercase letters

All command names, command page names, and redirects should use uppercase letters for the first letter of every word. An example is the text in the quick T-Series command reference for command #16:

#Store Current Position*

The redirect link must appear exactly as it does when including the command page for that command. Otherwise it will be a broken link. Uppercase letters must be used for the first character of each word since some Zaber software parses the wiki to generate variable names, removing the spaces. Using all lower case letters would make the variable names difficult to read.

Command type

• If the command name is "Return ..." and the command data is ignored then the command type is "read-only".
• If the command name is "Return ...", but the command data means something, then the command type is "command".
• If the command name is "Set ...", then the command type is "setting".
• If it's listed in the reply-only section, then the command type is "reply".
• Otherwise, the command type is "command".