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 the MkDocs in markdown format compatible for rendering static HTML pages with the python-markdown library.
- 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
▾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.
The following Python Markdown extensions are enabled for use currently:
|admonition||Adds rST-style admonitions. rST suggests the following “types”: attention, caution, danger, error, hint, important, note, tip, and warning.|
|footnotes||Syntax for defining footnotes1.|
|tables||Create tables in Markdown.|
|toc||Add a table of contents|
An example of table of contents for this page inside of an admonition (note):
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.