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 theManage Rulesbutton." - Use
▾for those "carrot" drop-down menus. Renders: ▾ - For headings: only use title case for the first three heading levels,
#,##, and###. The remaining header levels should be sentence case.
Admonitions
The following Python Markdown extensions are enabled for use currently:
| Extension | Description |
|---|---|
| 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 |
Example TOC
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
./screenshots/. - Files should be named descriptively. For example, use names such as
adding-IP-address.pnginstead ofimage03.png. - 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>
Other Considerations
- 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.
