[Tracker] Doc status for Godot 3.0 release

[mhilbrunner]

Now that Godot 3.0 entered release freeze, I started to look which areas of the docs are ready for 3.0 release and which still need some love.

Things to do for docs before or when 3.0 releases

• Change "Developing with C++" section name: The "Developing in C++" section name is ambiguous/confusing #933
• Make sure Google reflects 3.0 docs pages: Once 3.0 release, make sure Google search results reflect 3.0 pages #899
• Create 2.1 to 3.0 migration tutorial: Tutorial: Porting from 2.1 to 3.0 #537

Godot 3 Docs - Proofread and checked for 3.0 compatability

• General
  • About
    • Introduction
    • Frequently asked questions (Update FAQ for Godot 3 #951, Update FAQ for Godot 3 #945)
• Getting Started
  • Step by Step
    • scenes_and_nodes
    • Instancing
    • instancing_continued
    • scripting
    • scripting_continued
    • your_first_game
    • ui_introduction_to_the_ui_system
    • ui_main_menu
    • ui_game_user_interface
    • ui_code_a_life_bar (Fix errors reported in 'Control the game’s UI with code' #993)
    • splash_screen
    • animations
    • resources
    • filesystem
    • scene_tree
    • singletons_autoload
  • Editor manual
    • From Unity3D to Godot Engine (Improve C# intro docs/Unity transition guide #934)
    • Command line tutorial
    • Using an external text editor
  • Scripting
    • GDScript
    • VisualScript
    • C# (Improve C# intro docs/Unity transition guide #934, Create C# Scripting Page #924)
  • Project workflow
    • Project setup
    • Assets workflow
    • Export
      • Exporting projects
      • Feature Tags
      • Exporting for PC
      • Exporting for iOS
      • Exporting for Universal Windows Platform
      • Exporting for Android
      • Exporting for the Web
      • Customizing the Web export HTML page
      • One-blick deploy
      • Changing the application icon for Windows
• Tutorials
  • 2D
  • 3D
  • Audio
  • Physics
  • Math
    • Vector math
    • Advanced Vector Math
    • Matrices and Transforms
  • Animation
  • Inputs
  • GUI
    • GUI skinning
    • Custom GUI controls
    • Size and anchors
    • BBCode in RichTextLabel
  • Viewports
  • Shading
  • Networking
  • Asset Library
  • VR
  • Plugins
    • Editor Plugins
    • GDNative
  • Platform-specific
  • Miscellaneous
    • Background loading
    • Data paths
    • Saving games
    • Encrypting save games
    • Handling quit requests
    • Pausing games
    • Internationalizing games
    • Locales
    • Binary serialization API
• Development
  • Compiling
    • Introduction to the buildsystem
    • Compiling for Windows
    • Compiling for X11 (Linux, *BSD)
    • Compiling for OSX
    • Compiling for Android
    • Compiling for iOS
    • Cross-compiling for iOS on Linux
    • Compiling for Universal Windows Platform
    • Compiling for the Web
    • Compiling with Mono
    • Packaging Godot
  • Engine development
    • Introduction to Godot development
    • Configuring an IDE
    • Core types
    • Variant class
    • Object class
    • Inheritance class tree
    • Custom modules in C++
    • Creating Android modules
• Community
  • Contributing
    • Ways to contribute
    • Pull request workflow
    • Code style guidelines (Code Style Guidelines: Small fix #944)
    • Bug triage guidelines (Bug Triage Guidelines: Small updates #943)
    • Documentation guidelines
    • Docs writing guidelines
    • Contribute to the Class Reference
  • Channels
  • Tutorials
  • Resources
• Class Reference
  • Godot API

Note: If something is checked, that just indicates that I found no obvious outdated or missing information, links or media, not that the page couldn't still be improved.

Feel free to discuss/add comments or update this issue.

[vnen]

I would say that we should just delete the blatantly outdated pages (and sections of some pages) if we're close to release and no one is working on them. I prefer absent documentation than wrong documentation. Note that they'll still be available in the 2.1 branch.

[mhilbrunner]

Let's try to get as much as possible up to date before 3.0 release.

[NathanLovato]

How about using milestones so we can track and close all the issues as we go? Count on me to refine the 4 UI tuts pages - aside from that with the move to japan and work I don't think I'll have time to do much more.

[brainsick]

Concerning Step by Step. Roughly half of the tutorial projects have been updated for 3.0.

autoload.zip and robisplash.zip haven't been touched.

ui_code_life_bar.zip, ui_gui_design.zip, and ui_main_menu_design.zip all look to be in good shape.

instancing.zip has both 2.0 and 3.0 files, the .import directory, and some MacOS noise in the zip file. Is this intentional?

I'll look into updating robisplash.zip which encompasses splash_screen and animations.

[cbscribe]

instancing is way out of date. The screenshots are from Godot 0.99alpha. I started working on a rewrite just the other day with a new project file as well.

[brainsick]

I've completed the first pass of step by step changes and would appreciate a review. #966 If this meets community guidelines I can start working on something else.

I would like to follow this up with another pass at word smithing / flow and to update the resulting animation.

I would expect such an animation to result in a several megabyte asset (either gif or mp4) at the tutorial's 800x450 resolution for a brief clip. From a quality perspective, I would like to keep that native resolution. To wit:

Is it okay to commit such an asset to the repository?

Is it okay to host such an asset on YouTube and link it from the documentation? Is there a Godot account for this? Who would I hand the asset off to? Can Sphinx embed YouTube videos? Needs follow up.

One approach I've seen projects take is to open (and close) an issue, add assets as attachments, then use the resulting links as references ala:

https://user-images.githubusercontent.com/1111573/32465298-a5682c70-c308-11e7-978f-05457931806d.gif

Is that appropriate here? Will links break if users delete comments, issues, or their accounts? Needs follow up.

As you consider these questions, consider also that this is probably just the tip of the iceberg. Many places in the documentation could benefit from animations that could result in assets much larger than those being discussed here. Will the recommended solution scale?

[pwab]

@mhilbrunner IMHO #537 is one of the most important issues to be solved before 3.0 is released.

[pwab]

@brainsick

I would expect such an animation to result in a several megabyte asset (either gif or mp4) at the tutorial's 800x450 resolution for a brief clip.

• What is meant by "brief clip"? About what exactly?
• Gifs should be used for very small and short parts. They are getting huge very fast and no one wants to wait on a long gif to get restarted and they also can't be paused, played slowly, commented with subtitles/audio, be easily converted to different formats etc. ...
• If the clip is too long it should be made as video clip (mp4) but I am also not sure how to import such a video into the docs. The important thing is that no extra information should be provided in the clip which is not in the docs.

Will links break if users delete comments, issues, or their accounts?

• If a user deletes/edits a comment the uploaded images stay on the github servers (somewhere here) - though I couldn't find any docs about this
• An issue can't be deleted (and that is a good thing)
• If an account is deleted the user turns into a ghost and comments made in repositories owned by other users stay as they are

Will the recommended solution scale?

I don't like binding external resources into a documentation which is intended to also work offline (e.g. by exporting into an offline format such as html folder, epub or pdf). So by including externally stored information the whole "one package to store them all" concept (sorry for the pun) is gone.

IMHO this should only be done when you want to add another way of getting the same information but in a different kind of presentation or further information which is beyond the scope of this docs page. Like providing a video tutorial following the steps of the docs tutorial. Or providing useful links to additional tutorials/stuff.

[Calinou]

If the clip is too long it should be made as video clip (mp4) but I am also not sure how to import such a video into the docs. The important thing is that no extra information should be provided in the clip which is not in the docs.

Remember that a WebM video (preferably with the VP9 codec) should be provided as an alternative for browsers which do not support H.264 (such as the ones provided by several Linux distributions). It can be automatically converted using FFmpeg.

[brainsick]

@pwab

What is meant by "brief clip"? About what exactly?

I believe that tutorials should show, then do. I want to show at the top of the page the results of pressing Play in Godot upon completion of the tutorial, window trim and all in its full, glorious 800x450 resolution. The animation is only 1 second long, so a clip might be 1.2 seconds. I don't know, I don't have a clip prepared. This is hypothetical.

There are plenty of other situations where a clip could be useful. Multi-step processes that involve clicking on disparate parts of the UI can sometimes be demonstrated better by using animation than a series of still images.

I can't deny that this suffices in getting the point across:

http://docs.godotengine.org/en/latest/_images/out.gif

But is there no room for improvement?

I, personally, have no interest in recording video tutorials.

[pwab]

I believe that tutorials should show, then do.

Good point. I really agree with that.

I want to show at the top of the page the results of pressing Play in Godot upon completion of the tutorial, window trim and all in its full, glorious 800x450 resolution. The animation is only 1 second long, so a clip might be 1.2 seconds.

Then a gif should do the job. 👍 Not sure about the resolution though, but that can be discussed.

Multi-step processes that involve clicking on disparate parts of the UI can sometimes be demonstrated better by using animation than a series of still images.

In my experience this is not the case. I went through a lot of docs and everywhere this technique was used you get at least one of these problems:

• The docs can't be packaged to an offline format (epub, pdf). They also can't get printed. (gifs are represented by their first image)
• The gifs - when not absolutly high quality material - tend to be too long (showing too much), too fast (switching scenes, moving the cursor) or not straight to the point (in contrast: images try to show exactly one thing in the clearest way achievable)
• A lot of gifs used in a document lead to a huge load/download size. Disadvantageous for users who don't have highspeed internet or like to work mobile (Sometimes this also leads to heavy cpu usage)
• Sometimes (not quite often, but it happens): gifs fail to show the right region to click (especially in menus), the click at all can't be recognized and other such problems, which are hard to recognize for the creator (but are frustrating for the user)
• Tutorials containing such kind of gifs tend to be less wordy. The creator often relies on the ability of the gif to show everything needed to achieve a specific action. Users who understand mostly by reading are left behind
• Redoing gifs when the UI or the tutorial changes takes much more time/needs more work than simply take a screenshot (and mark a region) - so it tends to be not done at all

If no one sees one of these points applicable to the godot docs then - well - feel free to create as much gif illustrations as possible.

Please don't get me wrong here:
An introduction picture, a video or animation which shows where this tutorial will lead to is a big motivation for the reader and I can totally recommend it for things like your PR. But I am not a fan of using gifs (or multimedia in a wider sense) everywhere in one docs page. I believe the best medium is and will always be the text and some illustrating images. But maybe I'm old-fashioned...

[mhilbrunner]

Thanks to @skyace65 updating lots and lots of the outdated images, this will probably look a little better now. I'll check; hopefully, we can get a Godot 3.0 tutorial docs sprint going for the weekend.

[skyace65]

The Using tilemaps page is in desperate need of an update if anyone could do that. The screenshots haven't been updated since Godot 1.0 and I have no idea how out of date the information in that page is.

I know there's a lot of stuff that needs to be updated to 3.0, but I think it's important we don't neglect the 2D sections since that's an area where Godot really shines.

I'd update it myself but I don't have 2D assets to re-create those screenshots, and 2D isn't really my forte

[mhilbrunner]

@skyace65 (and for anyone else interested), assets suggested by @NathanLovato:

https://opengameart.org/content/lpc-tile-atlas or https://opengameart.org/content/lpc-farming-tilesets-magic-animations-and-ui-elements (it's under CC-by: http://lpc.opengameart.org/)

[NathanLovato]

Went back through the ui tuts and fixed all reported issues.

[ghost]

@mhilbrunner Is this list still relevant now that 3.0 has already come? Or do these pages still need proofreading?

[mhilbrunner]

@gemkibeju The non-checkmarked ones need to be checked:

• Do they need proofreading?
• Do they need to be updated for 3.0? (Screenshots, content)

The checked ones did receive at least one pass of updates. Not saying they can't be improved further though :) Will update the list further after GodotCon.

[Bauxitedev]

The InputEvent page is outdated. it says an InputEvent has a type member but in Godot 3.0 this is no longer the case. You need to do something like this instead:

func _unhandled_input(event):
    if event is InputEventMouseMotion:
        print("do stuff") # do something with event.relative.x for example

[mhilbrunner]

Fixed the page reported by Bauxitedev :) Also updated the list for reflect the current status.

[clayjohn]

If no one objects I would like to take a stab at updating the Viewport tutorial.

I would also like to add a short guided example for how to utilize Viewports to draw procedural planets like this:

Is that the sort of tutorial that would be welcome? Or should I stick to simply updating the current Viewport tutorial?

[cbscribe]

1. The current viewport tutorial could definitely use some love. There is definitely confusion about how they work, so go for it!
2. That example is gorgeous! Writing that up would also be a welcome addition. There's room for several different viewport examples in the docs, so the more the better

[mhilbrunner]

Finally closing this issue, as the majority of the docs are now updated.

For the remaining pages we find, we should open specific issues to track them.