Authoring guidelines

Who can contribute to this Wiki?

Anyone with a Compute Canada account. CC staff has the primary responsibility to keep the documentation complete and correct, but this is the age of Wikipedia. If a user spots an obvious problem, like a dead link or a typographical error, they are welcome to fix it. If you have a user who is willing to write an entire page, for example, on some piece of installed software with which they are more familiar than you are, they are also welcome to do that. We’ll review it once it’s posted to see that it meets these guidelines.

No anonymous editing is possible. You must log in with your Compute Canada credentials before you are allowed to edit, so we can tell who has done what.

What belongs on this Wiki?

This Wiki is not the place for information which properly belongs in the purview of the Compute Canada executive team, particularly the Executive Director of External Affairs (henceforth called the Executive). This obviously includes any communications intended for the general public, media or funding agencies. Materials related to training and outreach also don’t belong on this technical documentation site. To that end, ask yourself before you publish a page or make a change:

• Is this about what services or clusters are available? If so, has the service or cluster already been announced? If not, consult the Executive before publishing.
• Status information which changes on short notice --- available, offline, in maintenance, etc.--- will likely be the responsibility of the Monitoring Team.
• Is this information useful to a user, as opposed to other CC technical staff? If technical staff, then it might belong at https://ccdb.computecanada.ca/wiki/ rather than https://docs.computecanada.ca/wiki/.
• Does the information have implications for the security of our systems, or data on our systems? If so, consult the Director of Information Security before publishing.
• Is the information of interest only to a prospective user, as opposed to an existing account-holder? This is a gray area: A prospective user might want to know technical details about our services and facilities, the same as an account-holder, but if the information is only of interest to a prospective user then it properly belongs on https://computecanada.ca rather than https://docs.computecanada.ca/wiki/.
• External links may be appropriate, see e.g. "Getting an Account".
• Is this about how to use an existing service, cluster, or application? If so, go ahead.

Style guidelines

If in doubt, imitate the masters. Look at an existing page you like and follow the style. If there isn’t one at docs.computecanada.ca, look for one at Wikipedia.

• Separate graphic design from content as much as possible. Don’t use extra line breaks to adjust vertical spacing. Don’t indent paragraphs with tabs or spaces or add extra spaces after a sentence. If we want to make any such style adjustments we will make them universally using stylesheets and templates.
• Screen shots are good, especially in how-tos and tutorials. But full-sized screen shots interrupt the structure and flow of the text if they’re placed in-line. Let them float to the right-hand side. Also, scale the image down. If that makes important information unreadable, maybe a cropped picture is better? Or, remind the reader in the caption that they can "Click on the image for a larger version."
• Minimize use of synonyms. Yes, it makes the text less boring, but for a new user or one reading in a second language, interchangeable terms (e.g. "machine", "host", "node", "server") may be confusing.
• Leave one blank line at the end of each section before the following header. The translation package uses the blank line and header to determine the boundaries of translation units.

Templates

There are multiple templates, available. Please use them as appropriate. Of particular interests are templates for Including a command within the wiki and for Including a source code file within the wiki.

Translation

To translate a page, one first writes the content in the original language. Second, the page is marked for translation. Then, a human translates the page using organizational tools provided by the wiki extension Translate. Tutorials for this extension can be found here. Finally, a second human reviews the translation. If a page has not yet been translated, users can see the page in the original language. If a translation has not yet been reviewed, users can see the non-reviewed translation.

Marking a page for translation will trigger an analysis of the content of the wiki page. The page content will be split by the extension into so-called translation units. Translation units can be a title, a paragraph, an image, etc. These small units can then be translated one by one, ensuring that a modification to a page does not trigger the translation of the whole page. This also allows tracking of what percentage of a page is translated, or outdated.

How does one mark a new page for translation ?

When you have written a page, you should tag it for translation. Here are the steps to do so:

1. Ensure that the wiki code to be translated is enclosed within <translate> </translate> tags.
2. Ensure that the tag <languages /> appear at the very top of the page. This will show a box
3. Go in “View” mode, and then click on the “Mark this page for translation”
4. Review the translation units.
   1. Try to ensure that no wiki code (tables, tags, etc) gets translated. This can be done by breaking the page in multiple <translate> </translate> sections.
5. In the “Priority languages” section, write either “fr” or “en” as the priority language, that is, the language into which it needs to be translated.
6. Click on “Mark this version for translation”

How does one mark changes to a page for translation ?

First, try to mark a page for translation only once it is stable. Second, if you do have to make a change to a page that has been translated, make sure you do NOT change the tags of the form <!--T:3-->. Those are automatically generated.

Once you have done your edits, you can mark the changes to be translated by doing the following :

1. Ensure that the new text to be translated is enclosed within <translate> </translate> tags.
2. Go in “View” mode. You should see the text “This page has changes since it was last marked for translation.” at the top of the page. Click on “marked for translation”.
3. Review the translation units.
   1. Try to ensure that no wiki code (tables, tags, etc) gets translated. This can be done by breaking the page in multiple <translate> </translate> sections.
4. In the “Priority languages” section, write either “fr” or “en” as the priority language, that is, the language into which it needs to be translated.
5. Click on “Mark this version for translation”