Skip to content

Conventions for Examples

Jump to bottom
Rene Beckmann edited this page Jul 12, 2016 · 13 revisions

You want to create and submit your own example? Great! While doing so, please stick to the following conventions:

Example Directory

Each example must reside in a directory of its own within the repository's root directory. Please choose a descriptive directory name! It must be lower case with words separated by underscores.

  • Example: coffee_machine

Description

An example should have a description. The documentation must be in HTML, and it must be in a file named index.html on the top level of your example directory.

  • Example: coffee_machine/index.html

Please use the following HTML code as a template for your index.html file and modify it as needed:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>The Example's Title Goes Here</title>
<link href="../css/style.css" rel="stylesheet">
</head>
<body class="body-container">

  <h1>The Example's Title Goes Here</h1>

  <p>The example's description goes here in HTML format.
    You can use images like this one:</p>

  <p>
    <img class="standard-image" alt="The state machine"
      src="images/the_state_machine.png" />
  </p>

</body>
</html>

Image Directory

Images must be contained in a directory named images.

  • Example: coffee_machine/images/the_state_machine.png

Model Directory

State machine models should be contained in a directory named model.

  • Example: coffee_machine/model/coffee_machine_01.sct

Names of Files and Directories

Names of example directories must be lower case with words separated by underscores. Files within example directories and subordinate directories should follow the same naming convention.

Example Title

An example must have a title which should describe the example as concise as possible. The title should be title cased, for example This Is A Title. The title must occur identically at the following places:

  • as the <title> element in the index.html file,
  • as the first (and only) <h1> element in the index.html file,
  • as the title attribute in the metadata.json file.

No Generated Artifacts in the Repository

Generated artifacts, like C or Java sources produced by a code generator or binaries produced by a compiler do no belong into the repository. If any manual steps are needed to reproduce such artifacts, please describe them in your example's documentation, i. e. in the index.html file.

Clone this wiki locally