Examples README.md Guide

Jeff Gray edited this page Feb 20, 2016 · 1 revision

Return to Example Process Flow

This document provides a breakdown for key elements of creating a README.md, to be provided in the root folder of an individual example in the openFrameworks repository.

Key Elements

Each example should have a Markdown file, README.md, which contains the following:

  • Screencap image and/or Animated GIF that lives alongside the README.md file. Some tools for creating screenshots:
    • LICEcap - for directly screengrabbing to animated GIFs.
    • ImageOptim - to minimize image size
    • Jing - to create annotated screenshots/movies

In the README, this outline should serve as a template.

  • Learning Objectives
    • "This Example is designed to demonstrate:"
    • "How to {do a certain thing}"
    • "The ability of openFrameworks to {feature}"
    • Guides the reader to what's important in the code of the App *Expected Behavior
    • "You should see {description of screen}"
    • e.g. "Try moving your cursor left-right in order to....",
    • "Press to clear..."
    • If there are a lot of key commands, it's not necessarily appropriate here to give detailed instructions about what every keypress does. The In-app Overlays should accomplish that. It may be enough to say something like, "Keypresses allow the user to select among various different effects."
  • Other classes used in this file
    • See "customEventExample" in ofApp.cpp
    • Link these classes to their respective documentation page (where appropriate)