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.
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:
Note I've rated the documentation
- 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
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.
Enhancement Help Wanted Question Docs