[Specification Sheet] Tutorials, MWEs, Guide to Best Practices

christian-rli commented 5 years ago

As a user I would like to see examples (Jupyter Notebook Video Turorials API interface + Web interface) how my data gets into the DB to work fast and comfortable with the DB.

Create Tutorials that describe and explain what, how and where to upload (and download) data. Provide minimum working examples for all use cases and guide users to use best practices.

(This is a meta-issue, developed at a specification sheet workshop. The following issues contributed to it's creation. This issue can be closed when all sub-issues get closed and vice versa)

Full list of needed Tutorials can be found and edited here: https://next.rl-institut.de/s/zLMnFLSTdWSgKna

christian-rli commented 5 years ago

"Create Tutorials that describe and explain what, how and where to upload (and download) data. Provide minimum working examples for all use cases and guide users to use best practices." RequirementSpecificationID=15

christian-rli commented 5 years ago

"As a user I always want to see up-to-date tutorials to avoid following a wrong tutorial." - User Feedback All developers should document their work and make it easy to reproduce everything they have already done. @christian-rli may write automatic tests for jupyter-notebooks. Urgency-L, Time-M RequirementSpecificationID=15

klarareder commented 5 years ago

Best practices in video Tutorials: https://elearningindustry.com/instructional-videos-design-6-top-tips https://instrktiv.com/en/tutorial-video/ http://guides.libraries.uc.edu/tutorialtools/planning

What I found most interesting in these articles:

user a first-person rater than third person perspective
5-15 minutes or split video in small sections
at the beginning show what the result will be
meaningful titles
action and narrative at the same time (synchon)
do not speak and akt to fast, wait a second before the next action
speak in active voice not passive
highlight the mouse or areas of importance
make a scrip of what you want to say

Questions I have:

put the tutorials on youtube? - get feedback and statistics
do we want to be visible, e.g in the beginning? Apparently the people connect better if they see a face

klarareder commented 5 years ago

Can anyone recomend a good tool to record video tutorials? I found this: https://www.chip.de/news/Desktop-mit-Ton-und-Video-aufnehmen-Die-besten-Gratis-Bildschirmrekorder_93976623.html

christian-rli commented 5 years ago

@Ludee could you post the tools that you used for your tutorials?

klarareder commented 5 years ago

@christian-rli is this RequirementSpecificationID=15 and 19 or do we have another task for 15?

klarareder commented 5 years ago

I think we first need to make a table with what tutorials we need. The list will give an overview and we see what is already done and people can add new tutorial wishes. The colums could be:

Content | Type of Tutorial (Video/MWE/Blog/Jupyter) | Assignee | Status (todo, in progress, testing, done)

Further columns: Maybe we need to include Windows/Linux if there is a difference Maybe we could make for each tutorial a seperate issue and save the issure number in a further column

I am not sure how to display this table here on GitHub. Is that easyly done?

christian-rli commented 5 years ago

RequirementSpecificationID=15 is for both of us and covers the creation of tutorials. RequirementSpecificationID=19 is my task and covers keeping tutorials up to date. I thought it best to keep it in this issue rather than to create a new one. This way I think I won't forget about servicing the older tutorials, while doing work on the new ones.

christian-rli commented 5 years ago

You can create tables in issues (like here: https://github.com/OpenEnergyPlatform/examples/issues/25) or in the wiki (like here: https://github.com/OpenEnergyPlatform/organisation/wiki/metadata). Just copy their syntax and GitHub should display a table for you. In any case, a table is a good idea!

Ludee commented 5 years ago

I use OBS for screen capture and OpenShot for editing. Both are open source and platform independent.

klarareder commented 5 years ago

RequirementSpecificationID=15 is for both of us and covers the creation of tutorials. RequirementSpecificationID=19 is my task and covers keeping tutorials up to date. I thought it best to keep it in this issue rather than to create a new one. This way I think I won't forget about servicing the older tutorials, while doing work on the new ones.

@christian-rli is this our parent task for both 15 and 19, or is 15 somewhere else? - the table and comment are part of 15

klarareder commented 5 years ago

I don't know what Tutorial is wanted in OpenEnergyPlatform/data-preprocessing#5

klarareder commented 5 years ago

@christian-rli can you please enter the coresponding issues in the table. I hope you are the one who knows which line from the rquirement specifications matches which issue. I went through our redmine tickets and collected everything we noted on tutorials. I put a '?' as issue. If you have a corresponding ticket, please name it. Otherwise I would suggest that we discuss the tutorials in one of the next Jour Fixe: make sure there are no redundancies and add new suggestions.

christian-rli commented 5 years ago

@klarareder for clarity I created another issue for requirement 19. This is the parent issue for requirement 15 and (from now on) 15 only.

klarareder commented 5 years ago

@christian-rli could you please open an olny office document, in which I would copy the table. At the moment I can not work with it properly because of lack of functionality like (sorting, width over full screen etc)

christian-rli commented 5 years ago

Thank you for working on the list @klarareder . I created a nextcloud document and copied the table-content here: https://next.rl-institut.de/s/zLMnFLSTdWSgKna

klarareder commented 5 years ago

I edited (pasted the link into) the first comment so we find the table more easily and deleted the table in the comments, to make sure everyone is working on the same document.

klarareder commented 5 years ago

We decided in a SzenarienDB Jour fixe to:

put the tutorials on youtube? - get feedback and statistics

yes - this is better for stable performance and tutorials may get big so that this saves us space But we need to be cautions:

Do not select youtube licence - use CC by 4
state that we do not make money with this, otherwise we will have commercials in our tutorials

do we want to be visible, e.g in the beginning? Apparently the people connect better if they see a face

no, we think it is overrated

klarareder commented 5 years ago

I made my first test tutorial and while doing so I wondered: 1.) Do we want to have always have the same start? A logo + music + same text along the lines of "Welcome to antother tutorial of the OpenEngery Platform. Todays tutorial is about ..." 2.) Do we want to have the same end? Something like: "I hope you enjoyed this tutorial. Thank you for listing. Feel free to check out our other tutorials. We are looking forward to you using the OpenEngery Platform."

christian-rli commented 5 years ago

I would say yes to both, but it should be very short for both as well. The last parts of our recording equipment has arrived last week and we thought about writing our first storyboard soon.

klarareder commented 5 years ago

I made an example for an Intro. Does anyone know a good place to share these files (mp4)? I could place it on the Filr but than it would only be accessible to members of SzenarienDB.

klarareder commented 5 years ago

@SzenarienDB Team: The Intro is now in the Filr

OpenEnergyPlatform / academy

[Specification Sheet] Tutorials, MWEs, Guide to Best Practices #8