Bureaucrats, cc_docs_admin, cc_staff
2,774
edits
Authoring guidelines: Difference between revisions
Jump to navigation
Jump to search
change some computecanada.ca links to alliancecan.ca
(Compute Canada -> Alliance) |
(change some computecanada.ca links to alliancecan.ca) |
||
| Line 10: | Line 10: | ||
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: | 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. | ||
| Line 55: | Line 55: | ||
=== Layout style === <!--T:15--> | === Layout style === <!--T:15--> | ||
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." | ||