Rezonator Guide with ReadTheDocs

[Georgio-Klironomos]

Background Rezonator is complex, so users need a Guide (documentation) to understand it and use it effectively. The Guide should be:

• informative; easy to use; easy to maintain
• support for visual elements
• version control (linked to GitHub)
• support for localization in multiple languages

Model To create the Rezonator Guide, a good model is the LightTag user guide. This online guide shows how to use ReadTheDocs and Sphinx effectively:

• LightTag: User guide The guide is especially relevant for annotation (Tags):
• LightTag: Annotating

What to do

1. Create documentation for Rezonator using ReadTheDocs.
2. Use Sphinx and RST for writing the docs.
3. Host the documentation on the documentation page of Rezonator.com (rezonator.com/guide).
4. Create links to the guide web page (documentation) from the Help menu within the Rezonator application..
5. The documentation should be closely linked to the GitHub website, to maintain it with version control.
6. Create localizations / translations into key languages for our users.

Examples

• LightTag: User guide
• LightTag: Annotating
• Folia tools
• Godot Engine (games)

Resources for software documentation Some key resources for learning:

• ReadtheDocs
• Write the Docs
• Write the Docs (Guide)
• Sphinx and ReadtheDocs for technical writers (blog))
• Sphinx and ReadtheDocs: Getting started (tutorial)
• reStructuredText

Resources for language localization

• Localization (ReadtheDocs)
• Localization (Sphinx)
• Okapi Tools (blog)
• Okapi Tools (main page)
• OmegaT

Additional context ReadtheDocs is used by LightTag.io and Godot for their documentation, it' really nice! See also the detailed discussion of translation issues under Localization (#513 ).

[johnwdubois]

Very good-looking, worth considering for our web page. (which could use an overhaul, someday....)

[johnwdubois]

I spent some time on the GitHub page for ReadTheDocs and for Godot - seems to confirm that this is a good choice for us.

[gtroiani]

@carlasuarezsoto, @aya-zep, @kstanaka these are the resources we will use for the documentation

[johnwdubois]

The guide needs to be up on Rezonator.com\guide.