Authoring Guide for CADES
Perhaps you've got some how-to documents tucked away in folders that you'd like to share with the CADES community. Or maybe you've discovered a way of doing things that would benefit other users.
We've assembled here the fundamental authoring guidelines for CADES user documentation.
Document and Content Preferences
- Documents should be created using markdown using the commonmark syntax.
- Oak Ridge National Laboratory (ORNL) uses the Chicago Manual of Style (CMOS) as a basic style guide.
- Define the first instance of every acronym in each document. Ensure that the long form is not repeated after it is defined.
- Buttons and links that the user should "click" should go in
code. For example, "Next, click the
📝in front of NOTES. Renders: 📝
▾for those "carrot" drop-down menus. Renders: ▾
- For headings: only use title case for the first three heading levels,
###. The remaining header levels should be sentence case.
Pictures and Images
Screenshots and images cannot be resized using markdown. Therefore, we embed
.html that is rendered when we publish the tutorial to the documentation site.
- Images and screenshots should be stored in a folder
- Files should be named descriptively. For example, use names such as
To remain consistent with other images in tutorials, please use the following
.htmlcode to resize, add a border, and open in a new browser tab when clicked. Note that you'll need to change the file name twice in the following code.
<a target="_new" href="screenshots/ssh_import_pub_key.png"><img src="screenshots/ssh_import_pub_key.png" style="border-style:ridge;border-color:#bfbfbf;border-width:1px;width:550px;" /></a>
- Have you redacted sensitive information from text and images?
- Have you removed information that is protected by copyright?
- Are you using a specific version of your software and have you included in the documentation?
CADES Brand Guide
The CADES brand helps define our resources and team culture. A portion of the guide is provided here to assist you in choosing a color scheme for your media and documentation.
- Using a Git Workflow for creating user content.