Standardize workflow for creating demo videos

[mstenta]

farmOS.org includes a number of screencast recordings that demonstrate specific features of farmOS. As the system continues to grow and evolve, it would be helpful to have a standardized workflow around creating/updating these videos.

I started a "demos" branch in the repository to begin exploring this. It includes a README.md file that describes a potential workflow/process.

[mstenta]

Here is the current content of the README.md file:

These videos demonstrate specific features in farmOS.

These scripts are used to create video demos of features in farmOS. Please read
this document and follow the recommended guidelines before making changes to
any of the scripts.

Each script has two types of content:

1. Directed actions (denoted with an asterisk: *), and
2. Spoken words (denoted with a greater-than sign: >)

For each script, there are two corresponding video files: one with a spoken
audio track, and one without. The one without audio can be used to generate
translated versions of the video.

Videos should be short and focused on a single feature or aspect of farmOS. The
goal is to have a collection of short videos that can be easiy shared via
hyperlink, or embedded in other documentation. Short videos are also easier to
update individually when new features or changes are made in farmOS.

Changing a script means that video and audio will need to be re-recorded to
match it. Changes to a script should not be committed to the repository without
also committing the updated video file. Therefore, scripts should only be
modified if there are significant changes in farmOS that would make the older
version obsolete, or if there are mistakes that need to be corrected.

[mstenta]

And here is an example script for the "Navigation" video:

# Navigation

> farmOS makes it easy to find the records you are looking for, and to add new
> ones.

* Hover mouse over the main menu links.

> The main menu links provide direct access to lists of areas, assets, logs,
> and people within the system.

* Hover mouse over action links.

> Action links are provided at the top of each page for adding new records.

* Hover mouse over map and plan.

> The farmOS dashboard includes a map and lists of tasks that need to be done.

* Move the mouse over map.

> The map will show all areas on the farm. You can click on an area to get
> direct access to the assets that are in it, and the logs that are associated
> with it.

* Zoom in on the map.
* Pan to an area.
* Click on an area.
* Click on another area.
* Click on link to list assets/logs.

> The "Plan" on the right will list tasks that need to be done in the future.
> If you have tasks that did not get done, they will be listed under "Late
> Tasks"

[mstenta]

If anyone is interested in leading this effort, I would greatly appreciate the help!

The screencasts that are currently up on farmOS.org were created with byzanz-record on Ubuntu: https://wiki.ubuntu.com/CreatingScreencasts

[mstenta]

If we want to get started on this, I think this would be a good first pass:

1. Decide which features would benefit from demos (we can use the list of videos I already created as a starting point).
2. Write scripts for each one.
3. Record the screencasts using the script.
4. Publish to YouTube and farmOS.org documentation (and maybe even stick them directly into the farmOS software, so you can watch them in context).

[and712]

i will try to help on this :)

Also i think the Contribute translated content function of youtube should be very great for this. https://support.google.com/youtube/answer/6054623?hl=en

[mstenta]

Great idea @and712 ! Thanks for the help!

[kirsten-mc]

We discussed this in the call on June 10th. Similar to @mstenta's comment on Nov 28, 2018, next steps will be:

• starting with existing videos, create scripts with actions and a script. (note that the script can be loaded into YouTube later and be translated, so be sure to use clear, grammatically simple language). These scripts will be in markdown, as formatted above.
• @mstenta to create a folder in the repo so that we can create pull requests.
• once the script is agreed, generate the videos, with or without audio, with captions burned in or separate for YouTube translation. I'll be using Camtasia for this; happy to discuss any other software options.
• pull request into the repo where they are already saved; discussion about how to host YouTube versions.
  List of existing videos can be seen here: https://github.com/farmOS/farmOS.org/tree/7.x-1.x/docs/demo
  @and712, do you want to take on any of these videos as your own project, or would you like to work together on a video to start out?

[mstenta]

Thanks @kirsten-mc for moving this forward!

create a folder in the repo so that we can create pull requests.

Right now all the MP4s are in /docs/demo - so maybe we could just create a /docs/demo/scripts directory within that?

[and712]

Thanks @kirsten-mc!
I think it would be nice to work together!
Currently I have little time, but in 1-2 weeks i will be back on board :)

[kirsten-mc]

Linking back to #15 (comment) where a screencast for how to contribute with GitHUB is discussed.

[kirsten-mc]

@mstenta, I'm just revising the navigation.md script. Some questions:

• are Action links always green, or will some users have it configured to be other colors?
• the logs that you can access from the map - are those logs about the area itself, or logs about the assets? - edit: I figured this one out, please ignore
• to soften the ending, I'd like to add a short tagline and animation. Do you have any existing taglines / one-sentence summaries / elevator pitches that I can use as a stating point?

[mstenta]

are Action links always green, or will some users have it configured to be other colors?

They are always green, yes. Good question though because they may change in farmOS 2.x, but that will require updated demos anyway.

the logs that you can access from the map - are those logs about the area itself, or logs about the assets?

They are logs about the area itself. The map also shows how many assets of a given type are currently located in the area.

to soften the ending, I'd like to add a short tagline and animation. Do you have any existing taglines / one-sentence summaries / elevator pitches that I can use as a stating point?

Cool idea! Perhaps we can give that some thought as a community. Open to ideas! Including this in the versions that go on YouTube would be great. Not sure if we want it on the silent demos that are embedded in the docs? I kinda like how those just loop.

Thanks @kirsten-mc!

[kirsten-mc]

Cool idea! Perhaps we can give that some thought as a community. Open to ideas! Including this in the versions that go on YouTube would be great. Not sure if we want it on the silent demos that are embedded in the docs? I kinda like how those just loop.

I'll post in the discourse group and see what ideas come out. It's easy to include or not include in the final processing.

[and712]

Hello :)
hope you both are good and the harvest season was (or is) great!

@kirsten-mc thank you for creating the first script 👍

Is there already a list of scripts we want to do?

@mstenta @kirsten-mc
i also think that the old demo video are a good starting point, but i also think we should provide videos from the use case side. e.g. "How do i create a harvest log for my corn", "How do i see all my logs related to field XY"

So we would have two different types of demos:

• Feature based
• use case based

[mstenta]

I like the idea of two categories of videos like you suggest @and712 ! I wonder where we would put those in the existing docs, or if it would make sense to add a new section? 🤔

Or... we have also been discussing creating a blog on farmOS.org for content like this. Perhaps this could be a series of video blog posts that demonstrate certain workflows. One of the nice distinctions we talked about with the blog is that we can make it explicitly clear that we do NOT update blog posts - and they are therefore "time sensitive". Whereas the docs themselves should always be up-to-date with the current version of farmOS. That is what distinguishes the "demo videos" we have been discussing here with more "tutorial" content: we will maintain/update one going forward, but not necessarily the other. The main point being: we need to establish a sustainable policy around what we maintain and what we don't. The less we have to maintain the better. :-)

Is there already a list of scripts we want to do?

My thought was our first priority could be to update the existing demo videos we currently have, and create a standard procedure for producing/maintaining these kinds of things moving forward.

All of the current videos are in the docs/demos directory: https://github.com/farmOS/farmOS.org/tree/7.x-1.x/docs/demo

[and712]

i looked into the videos and the pull request of @kirsten-mc

some questions what came to my mind:

Is there a reason why kirstens pull request is not merged?

default settings questions:

1. which modules should be enabled? (e.g. with the mushroom module enabled the asset list changes)
2. do we need a "default" farm for recording all of that? (i know there was a discussion about it, but i dont find it anymore)

[mstenta]

Is there a reason why kirstens pull request is not merged?

My understanding was that it was a work-in-progress, and we would get all the scripts for the other demos sketched up as part of the same PR. But I didn't make that expectation clear, so hopefully @kirsten-mc is on the same page.

which modules should be enabled? (e.g. with the mushroom module enabled the asset list changes)

I think for the demo videos that appear in farmOS.org/guide we should just have the default modules enabled (those that are installed by default when farmOS is installed).

The demo videos should not include modules that do not come with farmOS (like the mushroom module), because that is outside the scope of farmOS core. We should only have to worry about maintaining videos for core modules ourselves IMO. Other videos can certainly be created for other modules, but we should consider them separate from the core videos. We do have a /guide/community section with pages for community modules... but even that I am thinking we may want to break out to a different place in the future perhaps. All important things to think about moving forward - thanks for bringing it up! :-)

do we need a "default" farm for recording all of that? (i know there was a discussion about it, but i dont find it anymore)

Ah yes - some of the discussion has happened in different places, but the current plan is to:

1. Create a farm_demo module that provides demo content for a farmOS install
2. Install this module on https://demo.farmos.net and use that to record the videos

Here is the repo @kirsten-mc started for the farm_demo module: https://github.com/kirsten-mc/farm_demo

And here is some of the recent discussion: https://farmos.discourse.group/t/example-data-for-farmos/86

[kirsten-mc]

Is there a reason why kirstens pull request is not merged?

My understanding was that it was a work-in-progress, and we would get all the scripts for the other demos sketched up as part of the same PR. But I didn't make that expectation clear, so hopefully @kirsten-mc is on the same page.

That's fine - I just wasn't sure how else to trigger a review of the content. I'll remove the pull request.

Agreed that we should just have the default modules enabled - it should look as much like an initial installation as possible. We don't want to scare people with, "why don't I have this button?"

[kirsten-mc]

I think I may have done the demo_farm repo incorrectly anyway - I need to look at this when the kids aren't screaming in the background!

[mstenta]

No worries @kirsten-mc ! I've been super busy lately too (and I'm taking next week off), otherwise I'd jump in and help. But there's no rush, so any help is appreciated! Let me know if you have any questions or if I can help guide the process in any way.

Eventually we're eager to set up some more automated integration tests using the farm_demo module - but we'll cross that bridge when we come to it. :-)

[kirsten-mc]

I've added the Wolfe's Neck KML file to the Demo Farm and organised it as best I could. I suspect we should cut it down to a subset of the fields, for example the Pote Pastures area - otherwise there are so many different fields to contend with!

[kirsten-mc]

I've done up a KML import video from end-to-end here https://github.com/kirsten-mc/farm_demo/tree/master/docs/demo

I have uploaded:

• the script
• a sample file for the demo
• a video with audio and captions
• a video with audio but a separate caption file (for services such as YouTube)
• a video with no audio, for looping.

This doesn't have to be the final script or anything, we can still make changes and re-compile.

[mstenta]

I'm going to move this issue to the new https://github.com/farmOS/farmos.org-EXPERIMENTAL, which will be replacing this one as the canonical repo for farmOS.org in the near future.

It may need to move again (since the user guide will be coming from the farmOS repo itself eventually), but there are a lot of valuable ideas in this thread, so I want to preserve it in the new farmOS.org for the time being at least.