mccPeople who design APIs. I am begging you. It doesn't matter how "simple" or "intuitive" or "elegant" your API is. You need to include sample code.
Another thing I am begging of people who make APIs: When you include sample code in the docs, include the "using"/"use"/"import"/"#include" statements. Please. Please. I just pasted this inline sample code https://mlem.ellpeck.de/articles/ui.html#setting-it-up into my hello world program, and it's failing because the symbol "UntexturedStyle" could not be found. "Are you missing a using directive or an assembly reference?", asks dotnet. Yeah, probably?? because you didn't tell me what using directives I needed?!?
"But it's obvious" I'M READING THE "GETTING STARTED" DOCUMENTATION. OBVIOUSLY I HAVE NO BASIS FOR COMPREHENDING WHAT IS OR ISN'T OBVIOUS
One other recurring thing that makes me tear my hair out in documentation: You document the type of the argument/variable/return value, but you don't document the *units*. Okay, so it's a rotation. But is it in degrees? Radians? [0.0, 1.0)? Is this time parameter in seconds, milliseconds, nanoseconds, CPU ticks? What direction is "Z"?! What is the handedness of your coordinate system?!!
Did you know it's common for VR gaming APIs to specify units in meters? Like actual, physical, literal meters? Like draw a cube of size 1.0 and you can get out a tape measure and peek out the little gap between the headset and your nose and the cube is one actual meter wide? Doesn't that make sense? Would you have *ever* guessed that if I hadn't just told you?
Hisham@mcc Answering your questions: no! (And I'm happy that it's metric and not in yards or inches or furlongs or something!)
Owen Nelson@hisham_hm @mcc I forget what the deal is with Unreal Units, but IIRC they group in 16 or something which I found odd.
cassie
Oblomov
0xC0DEC0DE07EA@mcc that’s a pretty decent default unit of length, it would have been my guess. I’m pretty sure at least one 3D modeling program I’ve used defaulted to it (and the default cube was a cubic meter).
@mcc yes, I would assume that all graphics/simulation stuff used meters as their units unless explicitly specified otherwise
Ehproque has moved@porglezomp @mcc yeah, metric, right?
@ehproque @porglezomp @mcc even living in the US so not in my everyday life, all the 3d software I’ve used has had metric coordinate systems, like for their default physics engine settings.
Brandon Jones@mcc Too bad all the other points of confusion you listed still exist in VR. 😮💨
"I want to make this object 3 meters tall!" Done! Easy! 👍
"Now I want to move it forward 2 meters!" Woah woah woah! Slow down! Are you using Unreal? Unity? DirectX? OpenGL? What even is "forward"?!?
: j@fabrica:~/src; 
@mcc Yeah, don’t even get me started on mapping that onto augmented reality using commodity hardware, where you also need to calibrate the camera to determine field of view and distortion characteristics. I used to know how to calculate the units coming out of that transform, but no longer.
Rho@mcc I think that's the default for apple displaying usdz files, I would have guessed it was an industry standard
Scott Michaud@mcc Yeah that's been a recurring annoyance for me. "Welp, I guess I gotta try all combinations."
Uli Kusterer (Not a kitteh)@mcc Also, “a rotation”? You mean there are multiple rotations? Which one is it? Why isn't that part of the name, and since it's not, why isn't that part of the docs?
I loathe when people just take the name of a property, the name of the object it's on, slap an article in front and consider that documentation. There is *no useful information* in these docs, might as well be honest and delete them… (pet peeve when I do code reviews, sorry…)
Rob Jellinghaus@mcc This is exactly why I gave my sound library generic types Time<T>, Duration<T> and various T's such as AudioSample, Beat, and Second. Never had another unit-related bug. (Well, except in the actual unit conversion code 😅)
https://github.com/RobJellinghaus/NowSound/blob/master/NowSoundLibShared/NowSoundTime.h
Shane Celis@MCSpaceCadet That’s a good idea.
@shanecelis It's to the point that I cringe whenever I see "int" for anything other than a loop index. What KIND of "int" is it??? Or "float" and "double" for that matter.
AN/CRM-114@mcc Just like every timeout argument or configuration file entry randomly chooses seconds or milliseconds. Is it waiting for 3.6 seconds or an hour? shrug emoji
Josué Boisvert 
@mcc I don't remember where, but the most cursed thing I had to work with was half revolution unit, meaning a full rotation was 2.0, at least you just have to multiply by PI to get the radian but for a solid week I kept pulling my hair as to why my rotations where fucked up. Nowhere I looked mentioned it wasn't radians.
Jazz Rabbit 🐇🏳️⚧️@mcc NGL I want this as a cross stitch.