Rewrite documentation

[tobiasraabe]

Problem

The documentation needs to be rewritten as it is not clear what the aim of the project is and that the purpose is twofold. I will go through everything myself and will create an updated template. Most of the time I will not rewrite parts but restructure them. Suggestions are welcome.

Naming

I would propose that we establish a naming convention for the two parts, the image and the manager. The manager is a little bit fixed, but it could be renamed nonetheless. Both need a long and a short name. We should also decide that we use the same style (bold, italic, both?). Proposals:

• oTree Virtual Machine Image (ovmi, OVMI, oVMI)
• oTree Virtual Machine Manager (ovmm, OVMM, oVMM)

First, I thought that bold face might be pretty, but no one else does it (e.g. Django, Wagtail, JupyterLab). Maybe I am leaning towards the last abbreviations as only lower- and uppercase are ugly. What is your opinion @cataclysmic?

New documentation

The new documentation should have one part concerned with the image targeted at normal users and one part about the manager targeted at administrators of a lab.

GIFs

To add visualizations, we could rely on animated GIFs. They are small, without dependencies, easy to grasp (here and here created with http://www.screentogif.com/). Of course, there are drawbacks as the GIFs have to be short as there is no pause play button for now. A larger discussion on the topic GIFs for documentation is here.

• maximum length of 10, 15 seconds
• start frame displayed with font size 40 for 2 seconds, white font on black background