Improve help and documentations

[xhdong-umd]

Preparing for the coming Animove course, I'll

• go through the app to improve the labels, names so that they are more intuitive and accurate.
• make screen recording demo for each page, showing the basic operations, adding subtitles as instructions.
• add help document in each page for
  • basic concept of the page, the position in the whole workflow
  • usage pattern for the page, link to the screen recording
  • some tips, hint on not so obvious points

Ideally I'd want to put the help link in a icon in the corner of box. This is not supported by Shiny dashboard yet. There are some user contributed attempts but not in a directly acceptable state.

Right now I just add a green button of help in places. If the icon in corner got implemented in future I'll move to that approach.

All the help documents are just markdown file located in help folder.

If you have any comment or suggestion on the labels, names in app, content of help document, please comment here.

[NoonanM]

@chfleming Once ctmm.select() has selected the best fit model, and analysis is at the stage where users visually inspect the fits, it might be helpful to provide a tip/hint on what a good fit might look like. For instance what it means if the selected model over- or under-fits the variogram, or how a fit might be improved by including ERROR if there is a lot of telemetry error that has not been accounted for.

[xhdong-umd]

Yes, I found this part not easy to grasp for myself. I made some tables and notes about the rules, and plan to include them in the help document.

Though the current task is probably more focused on documenting existing features, and I may need some careful planning on how to implement model selection in the app. That will be my primary task after June.30 because I need to work on another project soon.

[xhdong-umd]

I have finished the most of help documents. All pages that are working now has at least one help button to display the documents.

[jmcalabrese]

@xhdong-umd: Thanks for writing the help files. Do you mind if I commit changes (mostly minor edits) to the help files directly to the master branch?

[xhdong-umd]

@jmcalabrese No problem, changes in help documentation should be easy to manage.

Regular user cannot write to the repo so they have to fork the repo, commit and make pull requests. I thought that will be too cumbersome so I only asked for comments here. I forgot you can commit to the master branch directly.

Thanks for the edit!

[xhdong-umd]

Previously I planned to build an app website with blogdown. However I met a lot of bumps in using blogdown with certain themes. On the surface you have tools, themes and framework, but you actually need to learn a lot of details specific to the theme or framework to do anything other than the simplest example.

Since the app website should not be organized like a personal blog, maybe bookdown is more suit for this task. Then I realized there is not too much difference if I just put more content into the existing help pages in app.

If I add more words, especially screenshots into the help pages, they will become much longer. However a long document with screenshots might be actually easier to read than the dense text format.

I'll try to edit one or two pages and see the effect.