This repository has been archived by the owner on Mar 28, 2024. It is now read-only.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
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.