Plan structure for scripting and development documentation/examples on Confluence

[jenhicks]

I've drafted a first proposal here:

https://docs.google.com/document/d/1g_opGGRYfna8nLuWI3dEixa6VE5z8rQkqxVlO2BbnnQ/edit?usp=sharing

[jenhicks]

@jimmyDunne @chrisdembia @tkuchida @aymanhab @aseth1

[chrisdembia]

@jenhicks I could not make comments on the Google doc so I am making comments here.

I like the consistency of calling things "X Guide" (e.g, "Scripting Guide"). I also like making "Scripting Guide" a direct child of "Documentation".

There seems to be considerable overlap between the "Introduction to the OpenSim API" Confluence pages and the API Guide google doc. And I think the API Guide was also written with scripting users in mind, so it is not clear to me how we create a separate "Introduction to the OpenSim API (for scripters)" without introducing substantial duplication. Luckily, it seems that Confluence is able to import Markdown files (potentially from GitHub; see here and here), which would allow us to show pages from the API Guide directly in Confluence.

Current Developer Pages on confluence: Update and move relevant information to Github and/or Doxygen. Cut the old stuff.

In my opinion, the most important Developer Page is "Building OpenSim from Source." Should we leave the README as the only place for build-from-source instructions, or should we continue to maintain a separate Confluence page? It could be nice to continue having this Confluence page, because we might need to make updates after a release (we cannot change the README for past releases, and the README is only tailored to building the associated specific commit of OpenSim), for example when a new version of Visual Studio comes out. The Confluence page can also describe the build process for multiple OpenSim versions. The main issue with a separate Confluence page is that there would be a lot of duplication. My preference is to leave the README as the only place for 4.0 build-from-source instructions, and add back a separate Confluence page in the future if we find that it's necessary.

Also, keep in mind that we now have two sets of Doxygen pages: "user" (for scripters) and "developer." This was done because doxygen contains lots of information unnecessary/distracting for scripters, but still essential for developers. I think the "Scripting Guide" should link to the "user doxygen" (which we could rename to "scripting doxygen," etc.).

As for the "Resources for C++ Developers," could we get away with external links to "API Guide" and "Developer Doxygen" on the Documentation page, or is it important to have a unified/central place for "C++ Developers" on Confluence important?

Other ideas on improving the structure of the examples and tutorials section?

We could consider organizing the examples by interface (GUI, XML/command-line, MATLAB, Python, C++). For example, the Examples and Tutorials page could be a table that has columns for (a) illustrative image, (b) interface, (c) topic/workflows (building models, extending OpenSim [plugins], optimization, etc.).

The section "API Examples" should be renamed to "C++ Examples" and we should consider moving the documentation of the "API Examples" to Doxygen (not sure about this though).

[jenhicks]

Thanks for the comments @chrisdembia. I updated editing settings I think while you were in the midst of reviewing.

My understanding of the API guide was that Ajay intended it more for C++ developers and C++ API users. This is worth discussing more. I don't think we should send scripting folks right to doxygen. But if there is overlap we can reduce/minimize, we should try to do this. This point will likely be easiest to discuss in person at an upcoming dev or opensim meeting.

My preference is to leave the README as the only place for 4.0 build-from-source instructions, and add back a separate Confluence page in the future if we find that it's necessary.

I agree with this.

As for the "Resources for C++ Developers," could we get away with external links to "API Guide" and "Developer Doxygen" on the Documentation page, or is it important to have a unified/central place for "C++ Developers" on Confluence important?

We have some materials written for how to get started as a C++ developer if you're coming from a Matlab background (1st chapter of the current developer's guide). I think that confluence seems like the best home for this material and it is useful to save, along with links to other relevant resources.

We could consider organizing the examples by interface (GUI, XML/command-line, MATLAB, Python, C++). For example, the Examples and Tutorials page could be a table that has columns for (a) illustrative image, (b) interface, (c) topic/workflows (building models, extending OpenSim [plugins], optimization, etc.).

I thought about this but I can think of at least a couple examples that use multiple interfaces. We might keep the same (or a similar organization), but add a table, like the one you suggest, which would be helpful.

The section "API Examples" should be renamed to "C++ Examples" and we should consider moving the documentation of the "API Examples" to Doxygen (not sure about this though).

I don't think there is currently an API examples section. But we might add a section, so there are Beginner, Intermediate, Advanced, and (C++) Developer examples.

[chrisdembia]

I updated editing settings I think while you were in the midst of reviewing.

Oh okay; I can now edit the Google doc. Let me know if I should copy my comments there.

I don't think we should send scripting folks right to doxygen.

I completely agree.

We have some materials written for how to get started as a C++ developer if you're coming from a Matlab background (1st chapter of the current developer's guide). I think that confluence seems like the best home for this material and it is useful to save, along with links to other relevant resources.

Okay; sounds good.

I thought about this but I can think of at least a couple examples that use multiple interfaces. We might keep the same (or a similar organization), but add a table, like the one you suggest, which would be helpful.

I didn't realize. I do like the current organization of the Examples and Tutorials page.

I don't think there is currently an API examples section. But we might add a section, so there are Beginner, Intermediate, Advanced, and (C++) Developer examples.

I was referring to this page, which shows up under "Advanced Examples" here.

[jenhicks]

Thanks Chris. I annotated the google doc already with the suggestions and questions from our discussion.

Thanks for clarifying about the API example page. This was a stop gap to make the examples in the Developer's Guide more visible. If we move the Developer's Guide examples, we can just get rid of this page.

[jimmyDunne]

Everything above sounds great!

One suggestion I have; The Handling of C++ Templates in scripting is buried on a PDF link in the Common Scripting Commands page. I would like to see that fleshed out into a stand-alone page; which can include conversion between C++ and Scripting, and examples for each data type.