_[as someone suggested this, I will open a thread for the main points Kyle brought up in this 007 megamail. First post is his original point. I could use some help with people adding the main points of what has been discussed since then.]
_
in my opinion, examples + documentation should be at the top of the
‘priorities’ list right now
arturo told me that he tried exporting doxygen documentation at one
point. i’d really like to see what that looks like. i don’t know if
it’s the solution, but there’s definitely something wrong with the way
things are now:
- the website has instructions both for setting up IDEs, and a
reference for core functionality - the readme.platform that comes with the release has some
instructions for setting up an IDE, and a couple comments about minor
idiosyncracies. it also refers you to the website. - there is no core documentation distributed with the release besides
the readme and examples - the header files are littered with things like:
// this does a crop from another image.
// NOTE: this will reallocate memory if the image types are
different, or if the w & h do not
// equal this images w & h
which is super important for people to know… but maybe in the wrong
place. and, personally, i just get really weirded out by the
inconsistency. the fact that some comments are aligned, some aren’t,
sometimes you see “NOTE:”, sometimes it’s in all caps, sometimes it
has a link to a url that is relevant, sometimes it is just a
high-level explanation that a few people understand, sometimes it’s in
the .cpp sometimes .h… etc.
i think we’re kind of at a turning point. OF was originally about
looking at the source to understand what is going on, and finding
little comments scattered throughout. it was meant to be an
introduction to C++ and to OF simultaneously. but now i think we’ve
worked away from that a bit, and need to embrace it. if you look for
the implementation of ofTranslate, you’re just going to see something
like curRenderer->translate(). it doesn’t make sense to write:
// this calls the current renderer, which might be opengl or cairo,
and tells it to translate
but that kind of documentation definitely has to show up somewhere! i
think the right way to go is to have really badass html documentation
that can live on the site and be distributed with the release. it
should have some tutorials (not examples, but explanations of the “how
and why”) and a reference (like processing’s, or the current OF
reference).
also, big shoutout to roxlu for his presentations. this exists
somewhere on the border between tutorials and reference, and has a ton
of super-essential information:
http://www.roxlu.com/blog/entry/145/openframeworks-007-presentations/page/
