Make docs a lot more fancy. ✨

[Nitwel]

File.Library._.Directus.Docs.-.Mozilla.Firefox.2022-01-07.01-42-32.mp4

Added images,icons,gifs for:

• App Guide / Content
• App Guide / User Directory
• App Guide / File Library

[benhaynes]

Love it! A few things:

• Can we make the inline icons any smaller? What font-size are these now? 18px? I want them as small as they can be while still being legible.
• Let's make sure the color for these buttons are variables so we can easily adjust them Docs-wide. We'll be updating our brand colors soon and I don't want to have to redo too much.
• We need to make sure we have really thought through the size, style, resolution, and branding of the screenshots/videos before we start producing them all. Let's discuss before we dive in here.
  • They need to be consistent
  • Easily created by any team members
  • Decide on Mac/Windows and Browser (for scrollbars/icons)
    • I personally like Mac only because it hides the scroll bars when not in use, which makes it feel a bit cleaner. This is very subjective though.
  • Exact pixel size, and potentially "zoom" the browser
  • What Directus color/branding will we use by default?
  • Light or Dark mode by default? I think light
  • Capture software, so we have high quality and consistent renders
  • Anything else?

CC: @rijkvanzanten

[benhaynes]

Also, where are these images/videos stored? If they go in the repo, will they significantly increase the package size? Can/should we store externally? This could lead to weird version issues and broken media in the future.

[Nitwel]

Can we make the inline icons any smaller? What font-size are these now? 18px? I want them as small as they can be while still being legible.

Icons are 18xp and button 32px, smallest i could do.

Let's make sure the color for these buttons are variables so we can easily adjust them Docs-wide. We'll be updating our brand colors soon and I don't want to have to redo too much.

Did that in the last commit. Except for custom icons as we would have to import them extra.

We need to make sure we have really thought through the size, style, resolution, and branding of the screenshots/videos before we start producing them all. Let's discuss before we dive in here.

I picked 1000x700 px in firefox using the mobile view mode. and the videos are recorded at 1250x875 24fps. (to make them smooth but small). Each clip will be arround 2MB to 5MB.

Easily created by any team members

Realisticly speaking, either we spend days automating these video generation to be run on a dedicated server or something or no dev would want to do all the setup required to record these videos. 😅

I personally like Mac only because it hides the scroll bars when not in use, which makes it feel a bit cleaner. This is very subjective though.

Yes, Mac is very clean but I don't own one so either you buy me one 😉 or someone who owns a mac has to create them.

What Directus color/branding will we use by default?

Do you mean that the top left color is violett?

Capture software, so we have high quality and consistent renders

I used OBS

Also, where are these images/videos stored? If they go in the repo, will they significantly increase the package size? Can/should we store externally? This could lead to weird version issues and broken media in the future

Right now they are stored in assets (2-5MB per video) and as long as we don't beat the node_modules size we should be fine.

[rijkvanzanten]

Lets finalize this:

We need to make sure we have really thought through the size, style, resolution, and branding of the screenshots/videos before we start producing them all. Let's discuss before we dive in here.

@erondpowell you had some suggestions around the "rules" for these videos right?

As for what schema to use for the videos, I think it's fine if they're different installations (w/ different logos / colors), as it would only highlight the flexibility / different use cases

[erondpowell]

@rijkvanzanten

It is a bit too early for me to lay out any Grand Slam suggestions about the video.
I will need to get to know our unique conditions before I can put down anything super concrete.
But when I mentioned rules for videos, here are some of the basic things I was kind of thinking about:

Make videos scorm compliant.
Basically that means they are useful and actionable stand-alone, without any other learning content.

Define super clear-cut video types
Make them as specific and formulaic as insights panel types, with predefined intro, narration and outtros.
Simple examples of what this might look like:
Quicktips -> 60-360 second, tutorials that demonstrate one atomic feature or process, without nuanced explanation.
Overviews -> 3-7 minute demonstrations that highlight module features, what their capabilities are, and re-emphasize key value offerings and use-cases at the end.
Deep Dives -> 15-60 minute actionable tutorials, with real database, that highlight nuances of the app.
Tech Talk -> 10-60 minute semi-scripted coding interviews with team or community that highlight projects they work on, what they do, why they are doing it, and then abstract and discuss more use-cases and applications for the work being done.

Set script templates for each video type
Don't leave it up to the individual to guess how to write the videos.
Define rubrics/templates on how the video should flow and that also lets the video maker fill in the script/content directly.

Motion Graphics Templates
Essential to fast editing, staying on-brand and keeping content crispy.

The database schema thing
I think that's important!!! Nothing worse than doing meaningless, nonsense tutorials to try and rote memorize some "useful" process. BUT I definitely need more time to work out the details and give great feedback.

Using multiple installations is a super great idea!
My point was that the db installations should be thought-out, and somewhat cohesive.
Not a random "oh let's use a terrible and unrealistic social network database to highlight we could make social network databases".... Simultaneously, we don't want to use Facebook's data model.

PS How much of a time-crunch are we on for this?
I can provide clear examples on all this in 2-8 weeks if these ideas seem worth exploring.

[benhaynes]

All good points! No time crunch here, the priorities are:

1. Focus on improving/adding docs as needed (text) so we have better coverage features, gotchas, tips, concepts, etc.
2. Add screenshots to docs sections for better context
3. Enhance screenshots with videos, as needed. While we do need full specifications for all video types/lengths in time, the docs only need the short, bite sized videos.

As you've seen, we've already been cc'ing you on a lot of random docs issues... and beyond that, there are longer form technical articles/guides/tutorials to write. Let's keep the video conversation going, but prioritize the text first.

I'll let @rijkvanzanten confirm the initial specs for screenshots/videos, then we can start generating images while we hone in on video templates/scripts/format.

[erondpowell]

Awesome, I like it!