Write documentation for the UI

[marian-m12l]

Document the main concepts and the web UI.

[misterbenj34]

I can help on that. What should be the expected format ?

[marian-m12l]

Thanks!

I guess the appropriate format would be markdown to be readable directly on github. Maybe documentation should be moved to the project wiki, and the main readme simply point to the relevant pages.

As for the content, here is what I had in mind:

• Install and run instructions (already in the main readme)
• Web UI:
  • Main layout (navigating between library, device, editor)
  • Usage of the library (transferring, converting, etc.)
  • Usage of the editor:
    • The main concepts (pack metadata, different types of nodes, how it is played by the Lunii, ...)
    • UI usage (adding, selecting, moving, linking, deleting, duplicating, ...) (it may be useful to add short gifs to visualize actions)
    • Viewer (pack preview) usage (?)
• Recommendations regarding media assets :
  • Duration of blanks at the beginning (and end) of audio files: ~350-400ms for short sounds (questions, choices), 2 seconds for (long) stories (?)
  • Audio levels : peak around -3dB, mean around -20dB

Maybe also have a section like "Make (and transfer) your first story pack" ?

As well as anything that you missed or that you feel relevant :-)

WDYT? Really, any more doc will be an improvement, so we shouldn't wait for the whole doc to be written and well structured before pushing it. I'll look at the wiki and see how it works / how to give access.

[marian-m12l]

Corner-cases should also be documented. See for instance https://github.com/marian-m12l/studio/issues/23

[jin146]

I will help too as soon as I have mastered the basics.

[misterbenj34]

Ok, as I don't master Github, it's not easy for me to work on this. A wiki could help :)

But the way, I agree with the needed content 👍

[marian-m12l]

Hi,

Thanks for offering your help. The wiki on this project (https://github.com/marian-m12l/studio/wiki/Documentation) should be editable. Lmk if that's not working out.

[anoril1979]

Hi! === FR: Est-il possible d'avoir, à défaut d'une documentation complète, au moins un point explicatif sur les Stage Nodes et les Action Nodes ? J'ai tenté de les lier, mais sans comprendre à quoi ils s'attachent... Ni comment ça va se passer sur la boite une fois téléversé :P

=== UK: Is it possible to get a very short description, before having a complete doc, about how to deal with Stage Nodes and Action Nodes? I tried to make use of them without understanding how to link them to my story... And I don't even know how it will look once uploaded to the box :P

Merci ! / Thanks!

Paul

[marian-m12l]

@anoril1979 You're absolutely right! I started updating the wiki page to add some info. Might not enough, but I'll try to add more. Stage nodes and actions nodes are really tied to the story pack format understood by the Story Teller, and are not very intuitive to work with. Have you looked at the "simplified nodes" (cover, menu and story)? If you're really curious about the stage/action nodes, you can try to upload the example pack to your Story Teller and transfer it back to the local library. Then convert it from binary format to editable format, and open it in the editor. You'll see how the simplified nodes have been translated to stage and action nodes.

[anoril1979]

Gosh! Many thanks for the update! <3

I took an hour to try every combination and started to figure the thing out, but you greatly improved my inderstanding of the whole story ;) I can now see how powerfull it is and already start to create ramdom stories! Very fun.

Your tool is great and your help is too!

Regards,

Paul

[marian-m12l]

Thanks for the feedback! Please feel free to report any problem or potential improvements (to the app, the docs, anything).

[appenzellois]

I just copied the basic installation instructions to the Wiki and added some tips about how to fix some issues I had on Windows with the launch script (because of my particular Windows settings which isn't studio's fault).

I'm sure MacOS and Linux users have encountered other issues. It would be great if they would document them on the wiki as well. I added headers in the Wiki as placeholders.

[appenzellois]

Is there a way to add image to the wiki? I mean, the add image option points to an URL. I could upload images to my ftp, but if some day I delete them, what's gonna happen? Can't images added to the wiki be hosted directly on github? Or maybe we create a new topic for this purpose, upload pictures in the thread and point to their URLs in the Wiki ??