What user resources should we create?

[NauticalMile64]

Expected/Desired Behavior or Experience:

Users of every level should be able to easily locate official information to help them understand and use PlayRho effectively.

Actual Behavior:

The documentation is present, and the testbed is working on all platforms, but there isn't much other useful information for introductory users.

I know this is a broad and ill-defined issue, but early discussion can help us create a user experience which leads the user to the desired information as directly as possible (e.g. minimize flipping back and forth between the user manual, testbed, forums, and documentation to try and understand something).

The key here is that there are many different ways we can communicate how the library works, each with their own advantages / disadvantages:

Source	Clarity	Readability	Visuality	Tactility	Audibility	Maintainability
Source Code	Highest	Very Low	None	None	None	N/A
Code Comments	Moderate	Moderate	None	None	None	Moderate
Docs	Moderate - Very High	High	None	None	None	Easy
Developer Guide	Low - High	Moderate	Low	None	None	Difficult
User Guide	Low - High	High - Very High	Moderate - High	None	None	Moderate
Testbed	Low	Moderate	Very High	Moderate	None	Moderate
Examples	Moderate	Moderate	None - Moderate	None - Moderate	None	Moderate - Difficult
Tutorials	Low	Very High	None - Moderate	None - Moderate	None - High	Moderate - Difficult
External Forums or Mailing List	Moderate - High	Low - Very High	None - Low	None	None	Moderate - Very Difficult
email maintainers	Very High	Low - Moderate	None - Low	None	None	Very Difficult

These are all the common ways I can think of to get information about a software library. Are there any that I'm missing? Are there any categories I've not rated well?

All categories vary from None - Highest with the exception of Maintainability, which varies from Easy to Very Difficult.

Label	Description
Clarity	How precisely the channel communicate the capabilities of the library to the user
Readability	How easy is it for the user to understand the code or text present
Visuality	The degree to which the source communicates the library capabilities through diagrams, screenshots, animations, and live demonstrations
Tactility	The degree to which the user can interact with components of the library and see the results of their inputs, including sliders, fields, mousejoint usage, etc...
Audibility	The degree to which auditory channels are used to communicate the library capabilities to the user
Maintainability	How difficult is it to create and maintain the source. Factors affecting this scale include: The depth of understanding of the library the content creator is required to have The skills required to create the content (e.g. clear writing ability for documentation, good presentation skills for a video tutorial) The amount of content required How quickly the content is likely to become obselete Note I've rated the documentation Easy because it should be created whenever new code is added; the onus is clearly on the code author to do this, and it should be straightforward for them to describe the interface to their new code.

Given this information, which resources should we focus on creating?

Steps to Reproduce the Actual Behavior:

View the Github page and documentation so far.

[NauticalMile64]

After submitting this issue, my feeling that the User Guide is the most important is reinforced. Nevertheless, I'm interested to see what others think are the most valuable resources for users.

I've noticed however, that nothing really provides a really high level of tactility / interactivity with the library. The testbed is most like this, but if I want to create new bodies / joints / etc... that aren't already in a particular demo, I have to modify the testbed source code (which has the unfortunate side effect of dirtying my working directory as a developer), and I also have to compile and re-link to see the change. This means there's at least a few minutes before I see the effect of a code change. 😒 This is reasonable from a development standpoint, but very costly from a user who wants to experiment with different bodies / joints / setups as fast as possible.

[louis-langholtz]

Incidentally, I've been working on taking advantage more of doxygen's capabilities like by creating doxygen documentation "Modules". See the latest API docs for example and maybe ideas.

[louis-langholtz]

@NauticalMile64 I'd love to use the images — especially the animated ones — that I've seen you provide for examples of different types of elements!

Doxygen has an @image command which could be used to include the images directly into the API docs. We could save/accumulate these in the Documentation/images/ folder. And then use them from there in markdown docs as well as the Doxygen docs.

Update: I've created issue #113, #114, #115, #116, and #117 for joint classes that we currently have no images whatsoever for. I'd love to get images for these as a priority. The images for joints that we do have could probably all easily be improved but having any image IMO is better than having no image.

[louis-langholtz]

I've also been thinking that Testbed demos of new features/behavior/capabilities could be helpful. Added some issues for that.

[louis-langholtz]

How about information/guidance for porting Box2D code to PlayRho?

[louis-langholtz]

@NauticalMile64 I agree about needing ways to easily see how things work without a dev/compile/view cycle.

Towards helping with this, I've added JointsTest.hpp that shows off all the joints all in one place (as mentioned previously in the joints renaming thread). Here's a screenshot:

[louis-langholtz]

@NauticalMile64 I really like your question of what user resources we should create and the point about making it easier for users to understand and prototype the physics entities and behaviors.

Along these lines... pull request #188 (i.e. the code as of commit 4045f52) now brings a new Entity Editor to the Testbed. This gives a user of the Testbed more intimate knowledge of the settable parameters of physics entities and what those parameters can do. Entities like Body, Joint (all joints), Contact, and Fixture. Here's an image of what this looks like with some of the nodes opened for some of the joints:

Please note that this editing capability doesn't allow for creating or destroying physical entities; at least not presently. Also the new interface is not tuned yet to prevent or handle illegal settings which could cause exceptions or crashes.

[louis-langholtz]

Added issues #219 and #220 that add to addressing this issue.

[NauticalMile64]

I just built the most recent code and tried out the entity editor. Absolutely marvelous! This has really improved the utility of the testbed.