39,881
edits
Authoring guidelines/en: Difference between revisions
Jump to navigation
Jump to search
Updating to match new version of source page
(Updating to match new version of source page) |
(Updating to match new version of source page) |
||
| Line 1: | Line 1: | ||
<languages /> | <languages /> | ||
== Who can contribute to this Wiki? == | == Who can contribute to this Wiki? == | ||
Anyone with | Anyone with an Alliance account can contribute. Staff members have the primary responsibility to keep the documentation complete and correct, but this is the age of Wikipedia. An ordinary user who spots an obvious problem, like a dead link or a typographical error, is welcome to fix it. Equally so, a user who is willing to write an entire page on some piece of installed software with which they are very familiar, is also welcome to do that. The documentation team will review it once it’s posted to see that it meets these guidelines. | ||
No anonymous editing is possible. You must log in with your | No anonymous editing is possible. You must log in with your Alliance credentials before you are allowed to edit, so we can tell who has done what. | ||
== What belongs on this Wiki? == | == What belongs on this Wiki? == | ||
This Wiki is not the place for information that properly belongs in the purview of the | This Wiki is not the place for information that properly belongs in the purview of the Alliance communications team. This 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 the Senior Manager, Communications & Marketing before publishing. | * Is this about what services or clusters are available? If so, has the service or cluster already been announced? If not, consult the the Senior Manager, Communications & Marketing before publishing. | ||
* Status information which changes from day to day --- available, offline, in maintenance, etc.--- belongs on https://status. | * Status information which changes from day to day --- available, offline, in maintenance, etc.--- belongs on https://status.alliancecan.ca/. | ||
* Is this information useful to a user, as opposed to other CC technical staff? If technical staff, then it might belong at https://wiki.computecanada.ca/staff/ rather than https://docs. | * Is this information useful to a user, as opposed to other CC technical staff? If technical staff, then it might belong at https://wiki.computecanada.ca/staff/ rather than https://docs.alliancecan.ca/. | ||
* Does the information have implications for the security of our systems, or security of data on our systems? If so, consult the Director of Cybersecurity before publishing. | * Does the information have implications for the security of our systems, or security of data on our systems? If so, consult the Director of Cybersecurity 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:// | * 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://www.alliancecan.ca rather than https://docs.alliancecan.ca/. | ||
* External links may be appropriate, see e.g. "Getting an Account". | * 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. | * Is this about how to use an existing service, cluster, or application? If so, go ahead. | ||
If you still have any doubt, | If you still have any doubt, staff members should use the #rsnt-documentation channel in Slack. Non-staff contributors should contact [[Technical support]]. | ||
== Style guidelines == | == Style guidelines == | ||
| Line 29: | Line 29: | ||
The purpose of a style guide is to support writers in preparing technical documentation that makes learning easier. Carefully crafted documentation appeals to the user and delivers a positive image of the writer. | The purpose of a style guide is to support writers in preparing technical documentation that makes learning easier. Carefully crafted documentation appeals to the user and delivers a positive image of the writer. | ||
There are several style guides in circulation that set standards for computer documentation. Pioneers in this area are the Apple Style Guide and the Microsoft Manual of Style. | There are several style guides in circulation that set standards for computer documentation. Pioneers in this area are the Apple Style Guide and the Microsoft Manual of Style. | ||
There are no official writing guidelines for | There are no official writing guidelines for this wiki, but here are some simple and common practices we can readily adopt: | ||
* Design each paragraph around one idea. | * Design each paragraph around one idea. | ||
* Present the most important information first. | * Present the most important information first. | ||
| Line 44: | Line 44: | ||
: Yes, synonyms make a 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. | : Yes, synonyms make a 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. | ||
The word "system" is used frequently in computing with different meanings (legacy system, new | The word "system" is used frequently in computing with different meanings (legacy system, new system, cloud system, file system, module system, job scheduling system, GPU system, storage system, ''etc.''). It is not always clear to a new user what we are talking about. Whenever possible, please try to use a more precise word (cluster, storage space, scheduler, ''etc.''). | ||
==== External resources ==== | ==== External resources ==== | ||
| Line 51: | Line 51: | ||
=== Layout style === | === Layout style === | ||
When in doubt, imitate the masters. Look at an existing page you like and follow the style. If there isn’t one at [ | When in doubt, imitate the masters. Look at an existing page you like and follow the style. If there isn’t one at [https://docs.alliancecan.ca/ docs.alliancecan.ca/], look for one at [[wikipedia: | 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. | * 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. | ||
* Screenshots are good, especially in how-tos and tutorials. But full-sized screenshots 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." | * Screenshots are good, especially in how-tos and tutorials. But full-sized screenshots 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." | ||
| Line 91: | Line 91: | ||
#Click on “Mark this version for translation” | #Click on “Mark this version for translation” | ||
== Code blocks are not translated == | == Code blocks are not translated == | ||
Our professional human translator is not a programmer. | Our professional human translator is not a programmer. | ||
They cannot distinguish between code and comments in every possible language, | They cannot distinguish between code and comments in every possible language, | ||
| Line 110: | Line 110: | ||
= "Available software" page = | = "Available software" page = | ||
Tables on the [[Available software]] page are automatically generated from module files in CVMFS. In order to add a link to a new page from the "Documentation" column of those tables, add an entry to https:// | Tables on the [[Available software]] page are automatically generated from module files in CVMFS. In order to add a link to a new page from the "Documentation" column of those tables, add an entry to https://github.com/ComputeCanada/wiki_module_bot/blob/main/module_wiki_page.json and submit a pull request. | ||
Changes may take six hours to propagate. | Changes may take six hours to propagate. | ||