CADESUser DocumentationContributeAuthoring Guide

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.

You can submit your user guides for publication within the CADES documentation site! See the contributing page for instructions.

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 Manage Rules button."
  • Put 📝 in front of NOTES. Renders: 📝
  • 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.

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.png instead of image03.png.
  • To remain consistent with other images in tutorials, please use the following .html code 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.

Download CADES Abridged Brand Guide

results matching ""

    No results matching ""