Examples Contribution Process Flow
Quick Links - Inline Commenting Guide | README Guide | Overlay Text Guide | HOT LIST
If you're reading this, hopefully you're interested in helping make openFrameworks' examples even more useful, informative and self-describing, so they can be used most effectively with new and returning users. This document is a result of the oF Doc Sprint that took place at EDP in Denver, CO, February 17-20, 2016.
TL;DR - We're adding more context. To help out, skip down to How to Help to see recommended flow for adding to the documentation and staying consistent with the templates we've built.
Here's the active list of examples that have been claimed, completed, and are yet to be cleaned up.
To expand the usefulness of the examples, we're focusing on three main areas where Examples can be expanded. Below these are outlined, with a bit of our thinking behind each of the three.
The most direct, and least change-heavy of the three, we're combing through the Examples, expanding the existing in-line comments, primarily in the implementation file(s) of the example (.cpp, .mm) except for where specific actions taken in the .h files are of importance to the example in question.
- Best Practices Guide: Inline Commenting Guide
- Examples: customEventExample
Fully embracing the power of Github, where the project is hosted, we're creating README.md files in the root directory of each Example. We're also organizing the examples more contextually and providing category README.md files. This provides "landing pages" when browsing through the code on Github that can give you additional notes about the example without bloating the source files directly, and is also quite human readable when viewing locally on your computer. Additionally, we are dropping a screenshot .gif, .jpg, or .png alongside each README to provide a quick view of the application, making it easier to find that example you've used in the past and need again.
- Best Practices Guide: README Guide
- Template: Gist Template
- Examples: GraphicsExample
Finally, we're attempting to make overlay text consistent across examples where it can be useful. This text will appear on top of the sketch at runtime, and will universally be toggleable by the h (for help) key. This gives additional contextual information to the user, in a consistent fashion, and is the go-to location (along with the README.md) for listing the function of keys, clicks, and events in the example. To note, this is not being implemented in iOS/Android examples given the differences in keyboard functionality in mobile.
- Best practices Guide: Overlay Text Guide
- Template: Gist Template
- Example: easyCamExample
Instructions are aimed to make these changes as frictionless as possible for the project maintainers in Github.
Commit early, commit often, you're working in a branch specifically for this task. Go crazy. When you're feeling good about your work, and have pushed it up to your repo (or synced, if you're using the Github app), continue to final step...
To make a PR as easy as possible to accept by maintainers, make sure to merge the most recent master branch of the openFrameworks repo to your branch. Instructions and best practices for this are location here.
Upon clicking on "Create pull request", you'll be alerted if there are any comments/questions on your PR, and/or if its accepted into the code-base.
To note, please check out these docs for more information on the openFrameworks git workflow, the openFrameworks Coding style guidelines and the Issue and pull request management details document.
That's it! Thanks in advance for helping keep openFrameworks great!