godot icon indicating copy to clipboard operation
godot copied to clipboard

Improve the top docs sections of VFX classes

Open MewPurPur opened this issue 1 year ago • 3 comments

The top sections of classes are often one of the first things users read about them, so they are important to get right.

Improves the brief descriptions (mainly), main descriptions, and tutorial sections of many VFX-related classes (but not visual shader nodes). ShaderInclude docs was split off into its own thing and already merged.


Unlike my old posts, I've spent some time categorizing these by their importance, in case we want to nitpick.

Simple tweaks for consistency

  • CPUParticles2D, CPUParticles3D, GPUParticles2D, GPUParticles3D, GPUParticlesCollisionBox3D, GPUParticlesCollisionSphere3D: Add the article.
  • GPUParticleAttractor3D, GPUParticlesCollision3D: Use the "Abstract base class" opener. The latter also has a typo fix in its description.
  • ShaderGlobalsOverride, WorldEnvironment: Mention it's a node.
  • FastNoiseLite: Fix a grammatical mistake in the description.
  • Noise: Used [code] tag where appropriate.

Tweaked substantially, changed the flow of ideas

  • CompressedCubemap, CompressedCubemapArray, Cubemap, CubemapArray, Curve, FogMaterial, GPUParticlesAttractorBox3D, GPUParticlesAttractorVectorField3D, Gradient, GradientTexture1D, GradientTexture2D, Material, ORMMaterial3D, PanoramaSkyMaterial, ParticleProcessMaterial, PhysicalSkyMaterial, ShaderMaterial, Sky, StandardMaterial3D, VisualShaderNodeIf, NoiseTexture2D, NoiseTexture3D
  • GPUParticlesAttractorSphere3D: I get why we're using "ellipse-shaped" here even though it's wrong; I think we should be looking at "spheroid".

Doesn't fix a mistake, but still a tangible improvement

  • BackBufferCopy: The brief description had an absurd length, given it appears on places like single-line tooltips. Simplified it significantly and moved details to the main description.
  • BaseMaterial: Mention that it's an abstract base class. Update the title of the tutorial.
  • FogVolume: "Adding local fog" seems misleading, since the node is not just for adding extra fog. Saying that it overrides the global fog properties is more clear in that it can also mean adjusting or reducing the fog.
  • VisualShader: Links to the "Using VisualShaders" tutorial.
  • VisualShaderNode: Updates the title of the tutorial.

Fixes mistakes

  • PlaceholderCubemap, PlaceholderCubemapArray: The description says "texture's dimensions", which is a bit inappropriate as cubemaps are 6-layer textures with equal width and height. It's actually a copy-paste mistake that should be fixed in more "Placeholder" classes.
  • CurveTexture, CurveTextureXYZ: They don't "show a curve", that would imply the curve itself is displayed.
  • GPUParticlesCollisionHeightField3D, GPUParticlesCollisionSDF3D: These classes thought they were attractors.
  • ProceduralSkyMaterial: The description of this class makes reference of a few nonexistent properties and doesn't elaborate enough on DirectionalLight3Ds determining how suns are drawn.

Thanks a ton to Qbie, TMM, and Winston who helped with and workshopped for some of these changes in advance.

MewPurPur avatar Jun 30 '23 05:06 MewPurPur

I would suggest separating the changes that fixes clear errors in the documentation from stylistic changes for easier reviewing

AThousandShips avatar Jun 30 '23 10:06 AThousandShips

cc @QbieShay @hpvb @winston-yallow I would appreciate your reviews of the content since you have been personally named. 🙃

YuriSizov avatar Jun 30 '23 12:06 YuriSizov

I would suggest separating the changes that fixes clear errors in the documentation from stylistic changes for easier reviewing

I initially asked Yuri and he suggested I should split PRs based on area. I'll do this extra split if the docs team demands it, and I'll also do it for my following PRs.

I did it like this because I categorized the changes in the post-processing step, after I finished the PR.

MewPurPur avatar Jun 30 '23 20:06 MewPurPur

Feedback addressed again :)

MewPurPur avatar Jul 17 '23 00:07 MewPurPur

Duly noted!

MewPurPur avatar Aug 16 '23 13:08 MewPurPur

Thanks!

akien-mga avatar Aug 16 '23 15:08 akien-mga