openframeworks/openFrameworks — pull request #2765 by jtnimoy (2014-01-18 23:07:30+00:00)
Title: proposed way to write ofBook

per my email on [Ofbook] with thread subject "chapter breakdowns, next steps"

##My crazy structure idea for today:

1. We start adding new markdown files to the docs folder on master branch of OpenFrameworks https://github.com/openframeworks/openFrameworks/tree/master/docs

2.A. (the funnel technique) Authors can do a pull request on OF master branch, and as long as they are committing to docs or examples, the gate keeper should not be overwhelmed with too many key masters[1]. And anyway, I'm sure many of us authors are already added as github collaborators on OF, and so the pull requests would only be for us ghosts.

2.B. (the twin-groups technique) the docs folder could also be a separate repo, and sit as a sub-module inside OF. That firewall of access would greatly reduce the pull requesting, and the collaborators would be split into 2 groups.

3. the book, in relationship to the existing docs, need not have a lot of pomp and circumstance, and can just sit in the same folder, integrating into the current docs, adding to them, and pulling from them.

4. towards the end, the docs folder will just be filled with a bunch of topical markdown files, perhaps also containing with 1 assets folder. Examples that are full projects can (and probably should) just be in the OpenFrameworks examples folder.

5. we enhance /docs/table_of_contents.md with the new chapters. just as a suggestion for organizing to new eyeballs, we might consider dropping all non-TOC markdown files into /docs/chapters/ while leaving table_of_contents.md where it is, in hopes to increase the likelihood that a newbie would easily find their way to the book's main entry-point.

6. Later, it should be very easy to use pandoc to generate other accessible formats, including something that can be styled for paper publishing.

---

As a result, we gain Github's in-browser document editing, their fast drag-n-drop inline image embedding, and their C++ syntax coloring back-ticks. With the exception of "i see your cursors", this begins to exceed the 'pads for me.

In effort to bring in those inline comments from the OF code, it looks like Doxygen just started supporting markdown. http://www.stack.nl/~dimitri/doxygen/manual/markdown.html and if that's not enough, Doxygen also generates a more neutral XML file that can be parsed into markdown with a small script.