Where does help belong?

[DomClark]

This issue is to discuss where documentation and help should be kept, and how to make it available to users.

Most of the documentation for the software is currently only available online at https://docs.lmms.io/. Some recent changes and exceptions:

• The stable-1.2 branch has a "what's this" feature. This is rather incomplete and has been removed in master.
• master has a new "Xpressive" synthesiser which comes with a manual built into the software.

It would be useful for users to be able to access help offline. This could be achieved by:

• Providing built-in help within the software.
• Bundling the GitBook documentation with the main software download.
• Making the GitBook documentation available for separate download.

The following questions probably deserve answers:

• Where should new documentation go - in the software itself, as with Xpressive, or on the website?
• How should documentation be handled for changes that are as-yet unreleased or unstable?
• Once we decide where everything belongs, what should be done with existing documentation that belongs somewhere else?

Other related issues:

• Display hover-sensitive info in top right corner of toolbar #5571 - Display hover-sensitive info in top right corner of toolbar

Continued from #5570 as per @tresf's suggestion. Feel free to edit and discuss.

[Spekular]

I like the idea of making GitBook downloadable, but in combination with some in-software docs (as evidenced by me opening #5571).

• Where should new documentation go - in the software itself, as with Xpressive, or on the website?

I think shorter and more location-specific documentation is suited for hover text, everything else makes more sense on GitBook (probably with some overlap). "Time taken for note to reach full volume" is short and relates specifically to the attack knob of the envelopes tab. "Click an empty space to add a clip, double click to edit a clip, middle click to delete a clip, click and drag to move a clip, ctrl + drag to clone a clip ... " applies to the entire song editor timeline area and is super long.

• How should documentation be handled for changes that are as-yet unreleased or unstable?

I don't think we really "handle" this right now either, so changes going forward aren't likely to make things worse. I think it'd be ideal if merged features had documentation on GitBook even if they aren't in a release yet, so perhaps there can be a special section or separate book(?) for that? PR descriptions + discussion do a reasonably good job of documenting unmerged features, I think?

---

I definitely think we should continue to offer a docs-less download for those with poor internet, but at the same time it's good if we offer one with docs to make people aware of the possibility. One way I've seen this done is with an option in the installer, but if that's not possible maybe we could modify the download page? (quick inspect element mockup)

[tresf]

@Spekular I don't think we need a separate downloads for docs, no need to modify the downloads page, we should simply include the docs, always.

What'd be nice is if we could add a "more info" link which jumps to an anchor point in a PDF. I'm sure this is hard to do for all readers, but would allow use to somewhat integrate and avoid redundancies.

Previously, the standard way to offer help historically through Windows was to add a dedicated, searchable help window. I'm sure we could write a converter to do this but I'm not sure it's cross-platform.

Oddly, testing Google Chrome, MacPass and Slack, all "Help Centers" open in a browse window. Google's appears to be offline wherease Slack's appears to be online. MacPass just directs to a GitHub project page, not useful at all 🤣.

I feel as a project we should still ship with documentation. This is because music is often done offline (e.g. on a train, cruise, plane) and these are the times when people may need access to documentation the most.

1. GitHub sync the data from GitBook: https://docs.gitbook.com/features/pdf-export
2. Have the PDF accessible locally with install by default
3. Have menu items open to anchor points in the PDF

The way apps like Ableton tackle this problem is to have a dedicate help area in a small status bar at the bottom that can be clicked to launch more details information.

Another way to help this for Xpressive (a complex plugin which has a full code interpreter, sort of spurring this topic) specifically is to add something like commenting to Xpressive so that the usage is mostly self-documenting (and update the presets accordingly).

[tresf]

How should documentation be handled for changes that are as-yet unreleased or unstable?

Assuming we try to remove redundancies at all costs, I would recommend we document unstable features using the Since x.x.x or Experimental/Beta syntax. For example:

This may beg the question... what is "1.3.0" ? and that's an important "beta" versioning question that needs to be answered first, but I believe this solution allows new/experimental features to coincide with stable features. It also encourages more testing as people find the tutorial just to find the new beta and then to jump on the beta/testing bandwagon, something that's good!

[Rossmaxx]

for vst plugins, what about putting all documentation within the plugins (like whatever xpressive does). this can be done by adding a small qn mark icon on the vst plugin settings card. these docs can open in a seperate window/widget within lmms. for other things, we can consider some other options.

[rdrpenguin04]

We don't exactly have control over VSTs

[rdrpenguin04]

I was kinda wondering if we could have a tutorial embedded eventually, similar to what MuseScore has. Obviously not a development priority ATM, but it was brought up on the LMMS server today.