Bureaucrats, cc_docs_admin, cc_staff
2,879
edits
Authoring guidelines: Difference between revisions
Jump to navigation
Jump to search
Compute Canada -> Alliance
(Marked this version for translation) |
(Compute Canada -> Alliance) |
||
| Line 2: | Line 2: | ||
<translate> | <translate> | ||
== Who can contribute to this Wiki? == <!--T:1--> | == Who can contribute to this Wiki? == <!--T:1--> | ||
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. | ||
<!--T:2--> | <!--T:2--> | ||
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? == <!--T:3--> | == What belongs on this Wiki? == <!--T:3--> | ||
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.computecanada.ca. | * Status information which changes from day to day --- available, offline, in maintenance, etc.--- belongs on https://status.computecanada.ca. | ||
| Line 16: | Line 16: | ||
* 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 == <!--T:4--> | == Style guidelines == <!--T:4--> | ||
| Line 31: | Line 31: | ||
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 47: | Line 47: | ||
<!--T:14--> | <!--T:14--> | ||
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 ==== <!--T:19--> | ==== External resources ==== <!--T:19--> | ||