search

godotengine / godot-docs

Godot Engine official documentation
https://docs.godotengine.org
Other
3.98k stars 3.24k forks source link

[Tracker] Doc status for Godot 3.0 release #946

Closed mhilbrunner closed 6 years ago

mhilbrunner commented 6 years ago

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

Godot 3 Docs - Proofread and checked for 3.0 compatability

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 commented 6 years ago

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 commented 6 years ago

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

NathanLovato commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

pwab commented 6 years ago

@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.

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

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 commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

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:

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

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

ghost commented 6 years ago

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

mhilbrunner commented 6 years ago

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

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 commented 6 years ago

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 commented 6 years ago

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

clayjohn commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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.