This is a big topic actually. There are people that would like to contribute to a better documentation, I think we need to organise ourself a bit. In slack there is a channel for that (https://ofslack.herokuapp.com/, in case you are not signed in), but it is a bit empty. I would like to put some effort into it too, let’s discuss it there.
There have been a lot of efforts done regarding documentation but I feel that all these are not “glued” together well.
On one side, now each example (at least most of these) have a standard and nice documentation that’s written in markdown but it doesn’t show up on the OFsite, only in github. I think it could be useful to have it in the OF site.
On a different place we have the ofBook, which is great but I kinda feel that it goes unnoticed. Then there’s the doxygen generated documentation. Although it is not a 100% complete it is ok, as far as doxygen documentations go. I think that this is where the inclusion of markdeep would be super benefical. I also think that Doxygen documentation tends to be a bit cryptic for newcomers due to the nature of how it is generated.
So, I think that what would be really great is to redisign the documentation and learning sections of the OFsite. Maybe merging both into a single section? I’ll sketch some ideas and let you know.
On the contributor side, it is a bit difficult to figure out where to help. I wanted once to document how to draw lines with openFrameworks, I ended up writing another chapter of the ofBook, but I’m not sure if this is the right way to build the documentation. There is the high risk to pile up tutorials that are difficult to maintain. There is the high risk to build another section like the “how-tos” section on the OF website, http://openframeworks.cc/learning/, that it is in my opinion structured in a “stackoverflow” style, collecting short solutions to small problems, that user can copy and paste.
In my opinion we need to:
Improve the modules documentation. Because it gives an idea on the topic and on the classes involved.
Improve the Doxygen documentation
Clean up the examples, remove that ones that are strange or old (I remember an AdvancedGraphicsExample, that now is gone, but we should look into them and remove the old and weird ones, if there are).
Glue the things together. There should be a link in the module documentation that points to the examples on github, there should be a way from the ofBook to reach the module documentation or the examples. In general the user should be able to move from the big picture to the details just using the mouse.
I feel ofBook has been really helpful when it comes to learning certain things. However, there are some gaps that I feel should be addressed - for example the intro to openGL and the Shaders chapter could be combined together somehow or at least establish the facts how to integrate shaders into the openGL pipeline (and the much broader topic of the programmable pipeline inside oF itself). The advanced math chapter (Matrices) ha some overlaps with the intro to openGL chapter as well.
Also the ofxiOS chapter in the ofBook is really outdated, and there’s no mention of Android or Raspberry Pi in the platforms chapter.
A lot of the image processing stuff on the ofBook is fairly outdated as well (unsigned char * vs ofPixels getPixel(x, y) etc).
I’ve actually not seen the Doxygen documentation… is it the inline stuff in the actual oF libs? I’ve been jumping to definition a fair bit from Xcode to go see how certain things work and there is some fairly good documentation there but as @roymacdonald said, they might be a bit too cryptic for newcomers.
A lot of modules in the documentation (/documentation website) has very little to no documentation - which is sometimes really off putting It was fairly hard to navigate as a beginner.
Processing really does great module documentation with examples and descriptions for each function (usually) with code snippets and/or images. That would be ideal but I understand how cumbersome it would be to even try something like for oF - but for a few things it might be nice?
Bottomline, I think for users, the ofBook is a great resource which should be kept up to date and maybe new stuff added once in a while for how-tos, concepts, pipelines and stuff like that and, the documentation should be worked upon a bit to make it a little more user friendly, populated with more info.
Just putting down things I feel, I’d love to be involved and to help in whatever way possible
I think one challenge is that we have alot of different initiatives and it’s hard to know where we should put our energy . Things work alot better when we are all in one place but harder when distributed. We start alot of things and don’t finish them which makes it hard, there’s 3-4 incomplete places for documentation and better would be one place done well. I feel like we’ve always had trouble with this.
Overall I feel like OF book is pretty helpful but it was a ton of work to wrangle chapters and alot of them are a bit long, where it makes sense to keep things light. I feel like it’s overall pretty helpful and my students like it. I did take the denver conference to finish it and I feel like we can add small chapters but I would suggest we don’t spend much more energy on it, it feels the most done of all the documentation efforts.
I personally feel like the most important thing (since I teach alot of beginners) is a minimal API – something like:
which give beginners a leg up in getting a sense of OF – the most common things you need to do like draw shapes, load images, etc. I feel like this is something that could be off the main documentation somehow but organized nicely and friendly in the way p5 doc is friendly. This would skip alot of material – just focus on the most important parts of the api that an intro student would need. (ofSetColor, etc)
Second, would be some organizational work to make the documentation more friendly. Even just grouping vs alphabetical order can help functions make sense – for example
could be next to each other. It makes it easier to grok all the color related stuff.
I think it would be helpful for doing completeness on the docs and one way is to maybe have people “adopt” a class and maintain the documentation for that class, they way for example on the highway you see people adopt a section of the highway. There’s alot of work to be done but if it’s split up and different people take on a specific task it can work well. OF book worked because people took on a small manageable thing – they new they were focused just on sound or just on game design. That helps a TON to make it feel like it’s a task that can be done. It still takes work but it’s much easier that way.
It seems like we’re all on the same boat
I really like the processing/p5 documentation style. It is simple, easy to grasp and find.
@ayruos yes, the doxygen documentation is the one inlined. Doxygen takes all these from the lib files and format these into an html file.
The problem with this is that there’s almost no hierarchization which makes this documentation super large where all the functions and methods of all classes are listed.
A minimal API documentation as @zach is proposing would be superb. It could be a subset of the doxygen while using these markdeep thing to add all the nice things that the p5 documentation has.
I also like the adopting idea. I can do that for several classes that I’ve coded a lot (ofEasyCam, ofCamera)
As for the ofBook, I also really like it a lot. but certainly need updating. I wrote some time ago a chapter about ofEvents which has been sitting in the PRs for some time (I admit that there are still some things missing there, mostly some nice images inlined). I think that it would be super useful to have it merged. https://github.com/openframeworks/ofBook/pull/253
with an example, parameters, syntax and description. Plus, maybe, cross references, like links to the ofBook or to the examples on github.
This is just an example, but it is important that everyone is on the right path.
We also need to define a channel where to talk, it can be the forum but maybe it is better in slack, mattermost, or even in the dev mailing list?
@edapx thats a good idea.
Maybe the github issues is a better place for communication? it would keep track of everything, easy to address specific pieces of code or documentation and it is already there. We can have there some wikis with the guidelines too.
Ok, let’s do it on github, in the ofSite repository. I would start defining the guidelines, and try to keep it as small as possible, like the processing reference. I can write a first draft of it. Maybe in a wiki page.