MrBrax
commented
3 days ago Here are some I wrote up today, was about to make an issue after I would make some more:
- TypeLibrary usage and what methods can be used vs not whitelisted in Type
- Editor panels, control widgets, inputs, and how you use and design them in custom editors and editor apps
- Razor default elements and attributes like img, button, textentry
- Textures & Render target formats and what they're used for
- Material overrides, runtime material creation and attributes
- UI panel drag and drop, considering there are methods for it
- Gizmo usage, custom transforms
- Binding values in razor
- Razor render clarification, how to properly use buildhash and how child components render separately
- Creating assets programatically in editor, and how to properly use absolute/relative paths when you don't have the FileSystem.Mounted context
yuberee
matekdev
handsomematt
garrynewman
The term "Documentation" is usually a scapegoat for why developers have no interest in S&box, in this issue I'll try to compile what's missing.
Feel free to post your gripes here if you have any.
Courses
Every major engine has official courses, ranging from complete beginner to advanced:
The upside of having written courses compared to video tutorials is that they're easier to update in case there's any changes. Currently docs.facepunch.com is good at explaining what systems do and how to use them, but useless in the eyes of a complete beginner. Probably these courses will also need to explain the basics of C#, any extra work the user has to do to learn is developers lost.
Api References aren't documented
https://sbox.game/api is full of broken or straight up missing references and descriptions. Most methods, classes, and properties have XML summaries and remarks, they should automatically show up on the api pages as well. Here's just a few examples of the most used classes:
And generally it wouldn't hurt to have code snippets or manual descriptions on the most used methods or the ones that get grossly unused (Still seems like most people don't understand how BBox.Rotate works)
And while we're at it, would be nice if you could click on methods and classes inside of the
codesections in docs.facepunch.com, especially if courses get implemented.Still no templates
Templates were implemented over 2 years ago in June 2022, there are still no game templates available. I believe there are actually less compared to when the feature first launched.
I remember garry saying that the best tool for someone new to learn was addons, which was what made Gmod so easy to pick up. Modify a weapon stats, make them shoot exploding barrels, have the barrels roll towards players, and that could be a game by itself!
Not only are these templates great for piecing games together for anyone not confident enough to do it from scratch, they also serve the purpose of teaching correct programming conventions.
Original templates:
Current template(s?):
Regarding experience level
I'll bring up some points that were talked about in council chat, but I believe they're the general sentiment in the community.
When discussing what good Documentation criticism was, these were the kind of examples given:
In what world does the "good criticism" come from the mouth of a complete beginner? And how is the "bad criticism" not valid?
In general, it seems like the issue is being looked at from the eyes of someone that, to be frank, doesn't need documentation to the level of what the target audience actually should be. When people are complaining about documentation issues, they do so out of necessity, they're not doing it just to complain. (Althought I do agree most of the time it's used as a scapegoat from people too lazy to learn that feel called out)
Skilled programmers know how to navigate the api, know what to look for, how to look for it, decompile code, or find examples on github. The "documentation" they are looking for is fundamentally different from what the average Joe is asking for. Statistically speaking we have to assume that the biggest audience is made up of complete beginners with a computer that is barely able to run S&box tools and Notepad++.
Like mentioned before feel free to discuss, I'm hoping I can shed some light on the point of view of S&box beginners but unfortunately I'm becoming jaded too.