[osg-users] Call for assistance: Migrating and updating tutorials

[Björn Blissing]

robertosfield wrote:
> 
> I don't have a problem with video tutorial's, but as you say if API's change then videos need to be re-shot, but then other resources have to be redone anyway.  If one can make vidoes in a lightweight way then the cost of videos might not be too high.


The problem I have with video tutorials is that it is hard to keep quality consistent. This is a problem if the tutorials should be a community effort. This should not be seen as criticism of Michael Kapelko's tutorials. But I do not see how the community could build consistent video tutorials together. Another problem is that videos are next to impossible to change. Minor changes might be edited out, but often the videos would have to be re-recorded if the API changed or if someone found a bug.

In this aspect text is a much better format. It is easily editable and can be stored and diffed using a version control system. There may be language differences between tutorials created by different authors, but that difference is much more subtle compared to having videos narrated by different persons.

I have started experimenting with a OpenSceneGraph-Tutorials repository at home. So far I have made s quick draft of a table of contents, written a first tutorial and written the relevant CMakeLists to compile the tutorials. I started using markdown, but then I switched to Markdeep: https://casual-effects.com/markdeep/

Markdeep have better support for syntax coloring, diagrams etc. It can even be used to generate PDFs with acceptable pagination. Another benefit of Markdeep is that the content can be viewed locally since the only thing that is needed is a browser with decent javascript support.

Before I push this to a public repo I will write a couple of more tutorials just to see that the technology scales to a larger set of tutorials. For example, I still have not decided if the tutorials should be available as multipage (one tutorial per page) or single page (all tutorials in one page). The benefits of having a single page design is that you can easily print the document.

Regards,
Björn

------------------
Read this topic online here:
http://forum.openscenegraph.org/viewtopic.php?p=72201#72201