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

[Björn Blissing]

Hi Robert,

My idea is that this could evolve into a large set of tutorials. Every header in the TOC would be a separate tutorial, responsible for teaching a osg concept.

Each tutorial will have the one markup file containing the "lesson" and then the corresponding source code as separate files. The reason for including CMakeList files in every tutorial is to be able to do automatic testing.

The main index.md.html will only be used as the table of contents. The index.html file is only used as a redirect, as Github pages won't accept .md.html files as a landing page.

I took a quick look at readthedocs. Although it produces beautiful docs, it has one major drawback. It requires some setup and cannot easily be run for the client. Markdeep on the other hand is just a included Javascript file and can be viewed instantly on every modern browser, without any additional setup. Which makes editing and additions simple for the community.

Hopefully this explains my ideas a bit.

Regards
Björn

Den 20 nov. 2017 12:13 skrev Robert Osfield <robert.osfield at gmail.com>:
Hi Björn,

Thanks for your efforts on the tutorials.  I had a quick look at what
you have done so far, but am not yet clear how you are thinking it
might evolve.  I noticed both .md and .html files, are both something
that will be maintained?

On 19 November 2017 at 21:18, Björn Blissing <bjorn.blissing at vti.se> wrote:
> * Is this a tutorial format worth pursuing?

I quite like the idea of using github for tutorials, as it can easily
be placed alongside the main OpenSceneGrpah repository and maintained
in a pretty straight forward way. The format I don't yet have an
strong opinions on though.  Feedback from new members to the community
who are currently learning would probably be really useful.

> * Is Markdeep the right choice?

Possibly.

> * Is CCBY and MIT licenses that should be used for this project?

For a tutorial I think it would be useful having a license that allows
users to just grab source code and insert it directly into their
applications without having to worry about attribution/including
licensing.  Would this be public domain?  I'm not 100% sure.

The documentation parts would naturally fall under creative commons.

> * What C++ standard should the source code be written in (my suggestion is C++98 for maximum compatibility)?

Unless one is demonstrating use with later versions of C++ I think it
would be appropriate to leave it with CMake defaults like the OSG does
at present.

There is real value in having some C++11 and later tutorials as well.

Robert.
_______________________________________________
osg-users mailing list
osg-users at lists.openscenegraph.org
http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openscenegraph.org/pipermail/osg-users-openscenegraph.org/attachments/20171120/d6a41c3b/attachment.html>