Looking for feedback : What would be the most effective ways to learn APIs like the VulkanSceneGraph?

[robertosfield]

Hi All,

I am currently reflecting on how best to provide tutorial/documentation to help new VulkanSceneGraph users up to speed and being productive.

So far we have doxygen comments sprinkled in the headers, and I plan to expand this over time. I also want to have these automatically generated and hosted here on github, something I haven't yet out to do it, something I asked about in the thread #724.

We also have the vsgExamples and MyFirstVsgApplication repos that can be used but while there illustrates various features they aren't written in a tutorial form - there isn't any walking users through and introducing features one by one.

One of the intriguing suggestions in the #724 thread was the possibility of use ChatGPT. While this does a surprisingly good job it requires users to ask the right type of questions. I haven't experimented with it yet myself. Perhaps we can put example FAQ questions through it and see what happens. First we need to FAQ questions, so feel free to post questions you think would need answer in in Q&A form.

What is missing from all of this is providing a narrative flow through day 1 where users come across the VSG for the first time and then walks them through which features to learn first and one by one introduces more advanced features. So this is what I'm thinking about right now, and would be happy to get feedback from the community on how examples of this type of tutorial documentation that could be used to inspire my efforts in this direction.

If there are tools that work well for this type of documentation please let me know as well.

I am currently thinking of writing it mostly in Markdown files and if I can have a VSG based presentation that can read them and present them power point style but in full 3D. For the OSG training courses I used the OSG based Present3D for this but it required it's own custom XML format which I'd rather not adopt as I don't want to force users to use a tool to browse the docs.

[kannode]

Hi Robert, Markdown-based presentation is a good bet. I do not know if markdown does custom tags, but if it does, then things can be expanded as new tags are supported by vsg. Here is another thought.Sphinx and Restructured Text, which I know do support custom tags.

…

On Fri, Mar 10, 2023 at 7:15 AM Robert Osfield ***@***.***> wrote: Hi All, I am currently reflecting on how best to provide tutorial/documentation to help new VulkanSceneGraph users up to speed and being productive. So far we have doxygen comments sprinkled in the headers, and I plan to expand this over time. I also want to have these automatically generated and hosted here on github, something I haven't yet out to do it, something I asked about in the thread #724 <#724>. We also have the vsgExamples and MyFirstVsgApplication repos that can be used but while there illustrates various features they aren't written in a tutorial form - there isn't any walking users through and introducing features one by one. One of the intriguing suggestions in the #724 <#724> thread was the possibility of use ChatGPT. While this does a surprisingly good job it requires users to ask the right type of questions. I haven't experimented with it yet myself. Perhaps we can put example FAQ questions through it and see what happens. First we need to FAQ questions, so feel free to post questions you think would need answer in in Q&A form. What is missing from all of this is providing a narrative flow through day 1 where users come across the VSG for the first time and then walks them through which features to learn first and one by one introduces more advanced features. So this is what I'm thinking about right now, and would be happy to get feedback from the community on how examples of this type of tutorial documentation that could be used to inspire my efforts in this direction. If there are tools that work well for this type of documentation please let me know as well. I am currently thinking of writing it mostly in Markdown files and if I can have a VSG based presentation that can read them and present them power point style but in full 3D. For the OSG training courses I used the OSG based Present3D for this but it required it's own custom XML format which I'd rather not adopt as I don't want to force users to use a tool to browse the docs. — Reply to this email directly, view it on GitHub <#746>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHWFHIOLSPXTCFNH6AR6F6DW3MLNVANCNFSM6AAAAAAVWMLPKM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- S <https://www.nodein.com/>uresh K. Kannan, Ph.D., Chief Scientist, Nodein https://www.nodein.com

[HakanSeven12]

Do you hqve any plan about to provide a python api for it?

[robertosfield]

Is this an FAQ question to add to the list, or an actual question right now, if the later then could you create a separate topic for discussion as this thread is really about how best to present documentation rather than one for answering general questions.

[robertosfield]

Today I started learning/experimenting with using github Actions to create the required doxygen docs for each of the main VulkanSceneGraph projects and then generate github pages for them. I've a bit awkward but have finally got it to run the result is:

https://robertosfield.github.io/VulkanSceneGraphWeb/

My thought is this might serve eventually as VulkanSceneGraph project website, so vulkanscenegraph.org will take you to this site rather than the current crude generation of gtihub pages from vsg-dev/VulkanSceneGraph repo.

I haven't attempted any actual documents/tutorial writing today, it's purely experimentation to see what might be possible.

[Modenbach]

Hi Robert, that looks promising already. In our code we use a schort description of the module/class above the class definition. Like you said before: "/While impressively close to what we need, it misses the intent of vsg::Allocator and how it's actually intended to be used, i.e. it's used by the scene graph objects new/delete implementations to do block allocation of similar typed objects//." This would help a lot when diving into VSG the first time or just when looking for things you haven't done before. I thing doxygen is able to interpret such headers and insert the contents as a header into the documentation. Unfortunately I currently don't know which annotation is necessary to make doxygen accept it as such a header. Werner / Am 10.03.2023 um 21:19 schrieb Robert Osfield:

…

Today I started learning/experimenting with using github Actions to create the required doxygen docs for each of the main VulkanSceneGraph projects and then generate github pages for them. I've a bit awkward but have finally got it to run the result is: https://robertosfield.github.io/VulkanSceneGraphWeb/ My thought is this might serve eventually as VulkanSceneGraph project website, so vulkanscenegraph.org will take you to this site rather than the current crude generation of gtihub pages from vsg-dev/VulkanSceneGraph repo. I haven't attempted any actual documents/tutorial writing today, it's purely experimentation to see what might be possible. — Reply to this email directly, view it on GitHub <#746 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A4NEOA7SWODCLEW4UM7FINDW3OEEBANCNFSM6AAAAAAVWMLPKM>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[robertosfield]

Yesterday/Today I tried a different approach with using githib pages and have been able to create an closer to what might be appropriate for official vulkanscenegraph.org website, this includes links to the reference documentation generated by doxygen:

https://vsg-dev.github.io/vsg-dev.io/

It's not pretty, but at a basic level it is at least functional enough for be put up text/pictures/links to doxygen docs.

Could folks have a look at it. Let me know what you like, dislike, any typos, errors, link issues etc. that you come across.

For now I'm just using the default theme that comes with Jekyll. If you now how to customize the look that I'm open to suggestions. I particular I think the VulkanSceneGraph logo in the header and footer would be better than the VulkanSceneGraph text.

[robertosfield]

Also if you have projects you think would be good to add to the community project links on the Source page or screenshots to add to the screenshot page please let me know/provide the screenshots.