Markdeep on the OF documentation


#1

Hello, what do you think of having this https://casual-effects.com/markdeep/features.md.html in the docs http://openframeworks.cc/documentation/?

It can be easily integrated in Doxygen, https://casual-effects.com/markdeep/#api, it is actively maintained by Morgan McGuire and it is currently used also at Pixar.

I could take care of a PR if it is something that we want to try.


#2

Hi! What are the benefits of using it?


#3

It has a lot of features useful to write documentation.

Think for example to tables
https://casual-effects.com/markdeep/features.md.html#toc1.6

Admonitions
https://casual-effects.com/markdeep/features.md.html#toc1.10

Diagrams
https://casual-effects.com/markdeep/features.md.html#toc2


#4

Can this be enabled while keeping the documentation as it is, and later make small changes to the docs progressively to make use of the new features?

Adding one more dependency that needs to be maintained increases slightly the maintenance cost, right? Is it widely used or is there risk of it being abandoned at some point?

I think it would be nice if documentation did not need JavaScript to be readable, but unfortunately that’s not the case now either.


#5

I like the idea but we would need a lot of time and effort to transition to it. I’d be happy to help on such endeavor.


#6

Count me in as well if you need volunteers for this! :slight_smile:


#7

I do not think that this require any particular effort for the transition. I will try and let you know.


#8

Might be a good time to actually update some of the documentation as well - a lot of documentation is not that well maintained (or even blank) - so for that effort!


#9

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.


#10

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.


#11

I’m agree with you, and I think we should act on this front. To me, it is the lack of structure the main problem here, on two side:

  1. On the user side, there is no a clear way about how to learn things. And for “to learn things” I mean to get information about a topic in general, like for example “Sound”, and then go deep into the details. For the sound, for example, there is an excellent chapter in the OF Book written by Adam Carlucci http://openframeworks.cc/ofBook/chapters/sound.html, that gives a clear overview on the topic. Then there is the module documentation, http://openframeworks.cc/documentation/sound/, then there is the doxygen documentation for a specific class, for example http://openframeworks.cc/documentation/sound/ofSoundDevice/, and then there are the examples https://github.com/openframeworks/openFrameworks/tree/master/examples/sound, where a lot of effort was put in the last meeting in Denver, as far as I know. All these pieces of information are not connected together, a user is kind of lost and need to figure out by him/herself how to approach a topic.

  2. 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:

  1. Improve the modules documentation. Because it gives an idea on the topic and on the classes involved.
  2. Improve the Doxygen documentation
  3. 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).
  4. Figure out a clear direction and some guidelines for the ofBook. To me, these kind of contents are appropriated for such a resource, http://openframeworks.cc/ofBook/chapters/memory.html and http://openframeworks.cc/ofBook/chapters/sound.html, because they are introduction material that help the user to grasp concepts, but I’m not sure if articles that describe use cases, for example this one http://openframeworks.cc/ofBook/chapters/project_joel.html are in the right place. I like to read them, and I find them extremely interesting, but maybe they are a bit out of scope. And this lead to the main question regarding the ofBook, which is the main scope? That’s why I think we need guidelines.
  5. 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.

#12

From my own experience,

  1. 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.

  2. Also the ofxiOS chapter in the ofBook is really outdated, and there’s no mention of Android or Raspberry Pi in the platforms chapter.

  3. A lot of the image processing stuff on the ofBook is fairly outdated as well (unsigned char * vs ofPixels getPixel(x, y) etc).

  4. 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.

  5. A lot of modules in the documentation (/documentation website) has very little to no documentation - which is sometimes really off putting :cry: It was fairly hard to navigate as a beginner.

  6. 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 :slight_smile:


#13

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:

https://processing.org/reference/
https://p5js.org/reference/

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

enableColors()
and
disableColors()

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.


#14

good points about the book – I feel like some of it is that we took “tutorials” and folded them into the book since it seemed to make sense / de-duplicate content on the site.

I feel like doing chapter updates makes total sense – and updates to API, etc. The book was a ton of work to finish but it can def use revisions / consolidation.


#15

I like the idea to “adopt” a part of the documentation. Are we all agree that to make the reference page on the openframeworks website http://openframeworks.cc/documentation/ more similar to the processing one https://processing.org/reference/ would be a huge improvement to our documentation?
If the answer is yes, we have a starting point :wink:


#16

It seems like we’re all on the same boat :smiley:
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

So how shall we start?


#17

I think it would make sense to define a guideline, define what we mean for “minimal API documentation”. For example, let’s say that each method has to be documented like this:
https://processing.org/reference/ellipse_.html

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?


#18

It would be nice to have a description and usage and maybe some sort of a ‘scope’. For example,

ofDrawCircle(int x, int y, float radius)

Draws a circle at x, y with radius radius. Member of ofGraphics.

So then when we talk about ofSetColor or ofNoFill() etc we can say affects members of ofGraphics called after this.


#19

@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.


#20

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.

It is not clear to me if file like this one https://github.com/openframeworks/ofSite/edit/master/documentation/3d/of3dPrimitive.markdown are automatically generated by doxygen or if they are independent from it.