Feedback + Recurring issue WRT merge conflict

Hi,

Alright, we continue to sort through Addressables implementation. I've two main things here, one of which feels like it's probably a dead horse that continues to be beaten, but unfortunately, it is not apparent whether or not it's actually 'dead' and so the beatings shall continue! :-|

1) Merge conflict w/ 'Default Local Group.asset', taking "--theirs" (upstream) == nullref storm.
See screenshots linked below. This is probably a bug, but maybe not. I'm also getting tired of reporting bugs via the "official" reporting process (see tangentially-related #3). I've run into this same issue after a merge conflict now 3X, each of the 3X I've dealt with it I've had to take the same steps. Details are under each image in the link below.

DETAILS -- See these 3 Images w/ Respective Descriptions for each:
https://imgur.com/a/I6GuYtP​

2) The documentation is awful.
Some of the prior documentation versions were actually better than the current version's documentation, and that's honestly bewildering.

• 2A) Googling for documentation nearly always gets you to outdated documentation.
  It's great you've added a "latest version" link at the top, though that nearly always takes you to the 'top-level' docs (also a problem throughout ALL Unity docs pages), which makes it damn near useless since the search sucks. You're essentially traversing the namespace/class hierarchy, else you're back to Google to search again.
  
  I'd suggest either:
  • Setup 'Canonical URL' or HTTP headers to tell Google that the "canonical" (ie latest) version of the documentation for a given method and/or class IS the canonical version -- basically this would make sure that Googling for "loadassetsasync label unity" will take you to the latest docs page version.
  • Entirely "NOINDEX"-ing the out-of-date docs so that Google doesn't index them
  • Potentially using Schema.org markup to denote versioning on them, or likely some similar approach to let Google know that it's the "same page, just out of date"; I'm out of web/SEO for a while now, but I'm confident it's a trivially & perma-solvable problem with <=1 day of effort.
    
    
  • To illustrate this issue & make it really clear:
    Literally, please try: open a private/incognito window and search for "loadassetsasync label unity", and then click that first result. Oh, awesome you think -- except then you notice you're on the outdated docs. Ah, there's a "View Latest Version" link -- you click that, yay! Except now you're back on the Addressable docs home page. Well, that's right back where you probably f@#$'ing started -- so that's not helpful. Grrrr.
• 2B) Examples People Need / Want Are Almost NON-EXISTENT [in latest docs]!!!
  • As a quick & very obvious experiment, try this and see how quickly you can find example code that works (compiles & works at runtime w/out errors) to "LoadAll" / get back an T[] or IList<T> under these two circumstances (test w/ private/incognito for the full effect):
    • a) Using Resources LoadAll() -- suggested search terms include "LoadAll Unity", "Resources.LoadAll", and similar. Essentially all results are great & have working examples -- even if perhaps not the 'ideal' syntax, they're functional!
    • b) Using Addressables/Async Load All; suggested terms:
      "Addressables.LoadAssetsAsync" -- Outdated. No functional code/example.
      Basically any derivative of it, it "LoadAssetsAsync<T>" or "Unity Addressables load label", etc...
      You're going to almost always:
      • End up on an outdated page / old docs version.
      • Clicking "Latest Docs" is great -- but super rage-inducing, always goes to index(!!!)
      • If lucky enough to find it on the latest, it's almost surely going to be auto-generated documentation -- you'll be lucky to have the call signature documented. Code examples (and I'm talking 2-liners here) are nearly non-existent. Compare to the "Resources" loading documentation, where code examples exist & are functional.
      • The majority of the actual use-case & code examples that you will find via (google) search results are going to be on the Unity forums -- click on a few of those, and take a look at them; they're generally a bit concerning. Most will be talking about having issues/bugs, in some cases with a Unity rep noting "might be a bug", and most of them are dated late 2019-ish and have no follow-up.
    • Seriously, just try finding a working example: how to load all assets that have a specific label -- which one of these is right / what are the differences, and try answering these questions solely from the docs (it's not possible btw -- you will have to basically trial & error or get really lucky and stumble on a working code example from a forum post [likely a bug report] that may or may not still be relevant with today's API -- hell a semi-recent post suggests you may need to use brackets around your in-code label string):
      • Which of these is right, or what is different about them:
        • LoadAssetsAsync<List<TMyType>>("label");
        • LoadAssetsAsync<IList<TMyType>>("label");
          
        • LoadAssetsAsync<TMyType>("label");
        • LoadAssetsAsync<TMyType>({ "label"}, null);
      • What's the difference between these two (is big difference):

        • LoadAssetsAsync<TMyType>("label", myCompletedAction);

          
          
          

        • var x = LoadAssetsAsync<TMyType>("label", null);
          
          x.Completed += myCompletedAction;

      • Now, Google for how to load >1 assets using Resources.LoadAll -- ie from a single folder) or similar. I bet you can have a functional code example on-screen in <30 seconds. The disparity here should be pretty obvious, and it's not a small disparity, it's one of Grand Canyon-like proportions!
        
        FWIW -- I ended up getting it working after an hour or two; I don't know if the issue was related to my syntactical issues (ie the variations above), or if it was because my label had a "-" (dash) in it, or what. It'd be nice to find out, but it'd be even nicer to just have docs that explain precisely how to use this core stuff -- so we can just get on with gameplay code! I won't even start on "folder" loading; it suffices to say, it should have been a day-1 requirement / almost surely is the most common workflow.

3) I'm sick of reporting bugs via the "official" bug reporting tool.
Well, since I'm already ranting a bit here... The bug reporting process feels broken. Actually, I'm pretty sure it IS broken. Maybe not beyond repair, but there are problems here for sure.

• When Unity devs are asking for the ticket/reference # in the forums, it's a problem -- likely it's taking too long to go from "QA => developer" & so developers seek it out so they can do their job effectively and help people (because they care & want to do a good job). It may have other causes/underlying reasons too, such as QA struggling to understand/interpret/repro bugs, or similar. I'm quite acutely aware that this is a hard problem -- and exists in all major software projects -- but I know from experience that pretending that the system isn't a problem (or worse, that it "works well enough" / status quo) means you are quite likely to find yourself buried in technical debt "suddenly" (and by "you", I generally mean "leadership" -- because the devs almost always already know, or suspect it to be the case at the very least).
  
  
• Most of us that are using Unity in even a semi-professional way have games that are shipped or that are going to be shipping pretty soon. This poses several major issues with bug reporting:
  • We're asked for repro projects but they're often going to be massive.
    
  • Project "stripping" doesn't really work because assets are almost always required.
    
  • I get that "big & slow projects" are no fun to debug -- we ask our players to send us "minimal repro saves" whenever they report bugs, too. But when a bug happens on a massive save, we can't & don't ignore it. We even go to extremes to provide them a place to upload it, regardless of size. And then we have to wade through it, even if it's miserably slow to load & runs at 3FPS in the editor -- then that's what we have to do!!
    If the Unity editor (or a save file, in context of gameplay bugs) runs really slow on repro cases -- that's basically a bug in itself!! Bandwidth & storage is reasonably affordable & abundant these days, and IMO isn't a "valid" reason here.
    
    
  • The "lag time" between submission, to QA review, to Unity developer is massive and extremely high-variance. It's even worse if you're already-shipping your game & on an even-slightly older Unity version. And then you factor in when/where the fix will appear (ie the release management side) -- you can be talking 3-6 months or more in many of the "typical" cases.
  • It's extremely time-consuming to report a bug and to do so well. It's then rage-inducing when you go to those great lengths (taking time out of your project) to write up a good-to-great bug report & then it sits there for weeks+ before even being looked at -- and then receive mediocre response (ie in one recent case, 'cannot reproduce', despite including links to the GH issue in upstream Mono repo, the upstream commit that fixes the issue, and link to Unity Mono showing the fix isn't there).
  • My experience is that relaying a bug/case # on the forum is the only way the process "works" well / gets relatively quick & technically very-sound responsiveness (ie by the dev who's actually working on the codebase in question); in almost all other cases it's like tossing it into a black hole. During 2019.3x first few patch releases, for instance, lots of macOS issues -- wasn't even worth reporting them; you couldn't navigate a project for more than 10 minutes without a crash. I spent 45 minutes writing it up, uploaded a multi-GB project, it got to 100% then said "connection lost"/it failed out. Rage.
  • This is NOT globally applicable, but I've come across it a few times specifically in this forum/related to Addressables -- asking for repro projects that either have already been submitted or that shouldn't be needed. In some cases the submitted case was 'closed', maybe was fixed & is a regression, or was just overlooked -- but for whatever reason is failing and the repro was sent in. Other times, I've seen acknowledgement of a bug/problem in forum posts with no follow-up and/or with a request for a repro on something that's actually acknowledged as problematic; I get repro is challenging & time-consuming, but there is a point at which actively working with the tool/code yourself (read: dogfooding) does differ from "blindly" seeking out bugs. I get it, no one wants to "blindly" seek out bugs, but it also shouldn't be a matter of "don't move until a repro gets through the queue, QA verifies, and case opens on FogBugz" -- surely devs are able/allowed to open cases on FB direct...

Finally -- apologies in advance to the Addressables team, hah --you're getting the brunt of it from me this week because it's the area I'm working on right now. A few weeks back, some of the Graphics guys heard similar rants, though they are/were extremely helpful despite my occasional ranting related to frustration with some graphics/lighting pipeline & architectural/API decisions. I appreciate you guys, too! And apologies in advance if any of this comes off as personal -- I know/feel as though those of you "in the trenches" generally care quite a bit; if anything I feel like there may be some leadership/direction challenges, but I'm not sure and am not going to claim to have all the arm-chair-QB answers. That said, all I can do is give examples and provide feedback/experiences!

Anyways: Ty for your patience/putting up with me; there's nothing personal, and despite any frustrations voiced here, I know many/most of you at Unity sincerely care very much and I respect & appreciate that.

 

I'm a little confused on the steps...
1. you make changes to Default Group, as does someone else, you both commit to git
2. there's a conflict
3. you end up taking theirs
4. things explode.

That right?

I agree this is super annoying. There isn't really anything our team can do to address it, but I will get the feedback to the docs team. I thought the "latest" button was helpful, but had not realized that it reset you to "index". Not great since searching within the docs is challenging. I'll pass this along as best I can.

I would like to hide behind the tooling and format (and website) of package documentation, but know that's not fully to blame. There is a lot of room for us to make improvements here. For actual code samples, we try to refer people to https://github.com/Unity-Technologies/Addressables-Sample but that is both limited in scope, and rarely going to show up in google searches. I'll discuss with the docs team what our options might be. The Resources.LoadAll is a really good example. There you have one manual page that covers the two versions of the interface, without being cluttered by everything else under Resources. With packages, if we use the expected documentation format, you get one page for everything Addressables.*. I agree this is not helpful, and will explore options to make it better.

This complaint also makes sense. Where we can, when a user submits something obviously wrong on the forums, we make a ticket ourselves. Unfortunately, as a product matures, the broken workflows become more and more edge case. As that happens, it's harder for us to repro the bug from scratch.
Your git conflict bug is an even worse example. That one is difficult to repro from scratch AND difficult to create some sort of test project for.

I am a little confused by your comments about huge projects. Are you saying tickets are rejected because the repro project is too big? Or are you saying you are asked for a small repro, and are frustrated by the request?

I totally understand, and thank you for your feedback. As a weekend-unity-user myself I've had my share of frustrations, and understand your concerns. We really do appreciate this feedback. Up until now, we've known that the doc setup has not been good, but have been focusing on other issues more within our sphere of control. I will do what I can

 

Ty for the reply. Appreciate the thoughtful & detailed responses; apologies in advance for somewhat of "pent up" thoughts, but that's just how it goes.

Re: #1 (the bug) --

Yes, precisely. Given that I'm taking --theirs and presumably it isn't blowing up for them (else I'd expect to hear about it), my best guess is that it has to do with differing hashes because of different platforms, but that's definitely a wild guess. The end result is that the YAML has a "File: 0" or similar / a 'literal' null value in it. Then, the line shown in the screenshot is erroring (IIRC off top of my head) because it's using Linq on a collection that contains a null value.

FWIW, I'm working from macOS while all other devs on the project are running Windows. We're always precisely-synced in terms of editor versions, always using the same patch level.

Re: 2 --
That the teams differ wholly between "docs" and "functionality" may be part of the problem.

I'm not sure how you guys divvy it up, if someone gets "embedded" temporarily or if the docs team "floats" or is wholly distinct, or what -- but I've had to deal with this same organizational issue from the leadership level previously and it's certainly tricky. That said, passing the proverbial buck never works well as a strategic play towards documentation/SDKs/APIs. As best I can tell, from what little I know [so grain of salt], but it seems to me like there's a responsibility issue at play.

In organizations I've lead, we've always had the saying: "if no one is responsible for product" (and in this case, the product is 'Addressables' itself), including it's reception / dev usability / functionality / etc, "then no one is responsible".

Essentially means, who owns Addressables -- and are they truly empowered & capitalized (ie developers, technical writers, etc) to drive it to where it needs to be? Whether that's from a docs standpoint or from a usability/bug standpoint, etc... I think the answer is pretty clearly a "No", which is likely the real root of the issue (not just for Addressables, but in other areas as well); individually each of you seems to care greatly, to be competently skilled, and to generally put in very high amounts of effort. Whether any given individual has the authority & feels truly empowered to "move barriers" however, seems more questionable.

My guess is that the issue falls in this general area, far more so than any [individual or team] lack of want/care/desire; and to be clear, I don't believe this to be specific to Addressables, not at all. If anything, I think it's just becoming more obvious/problematic sooner in some 'areas' of the engine than in others, and there are other areas where it's been relatively evident for a while even (IMO at least).

Re: 3 --
It takes long enough to get a small, basic bug looked at by a real human. If you upload something massive, and it fails for any reason, at what point are you wholly disincentivized to spend the time trying to ship a repro? Answer is, very quickly; the first time I upload 2GB+ and it "fails at 99%", that's probably approximately very near to the last time. If it takes 4+ weeks for a small & easily reproducible bug to be reviewed, with a ~70% chance that it gets diagnosed correctly & a fix makes it into a future release. After doing that process a few times, you quickly find yourself in a spot where you feel it's a waste of time to upload a big project -- and you're far, far less inclined to report the small bugs you find outside of absolute show-stopper level critical bugs.

 

one more detail... is Unity open when you do the pull/merge from git? I'm guessing it actually has to do with something being in your Library and there being some importing weirdness. but the OS mismatch could also be it.

I may have been unclear here. We do have an embedded person on our team to help write docs. Well, a shared person, but still a single person for whom we get some time slice. Which is why I do believe, for the most part, the doc issues can be improved by us.
The piece that is a bit outside our scope is the doc tooling infrastructure. All packages have the same doc website. A main page with some markdown files, and an API page (like https://docs.unity3d.com/Packages/com.unity.addressables@1.8/api/index.html) that is generated. I was just wanting to say that, I agree with you there are challenges. And say that I will work to both improve the pieces within my control (the doc content) and do what I can to drive improvements in the pieces outside my control (tooling, websites, etc.).

I hear your pain here. What I'm not super clear on is what exactly you are suggesting. Is it that we improve the upload process, and make it easier to just submit your giant game? Or we make it so you can file bugs with nothing but some steps (no repro project)?
The challenge as I see it is, bugs generally fall into one of two scenarios. In scenario one, it's super hard to make a small/simple repro project. Here, it wouldn't work to submit a bug without a repro. If you the user can't reasonably make a project to repro this, how would we? In the second scenario, making a repro project is much more straightforward. In this case, it seems to me that it'd be simpler and more reliable if you made the project yourself, rather than try to write up detailed instructions on how we could do it.

I will also add, this isn't really a problem I can solve. If you have a good idea, I can definitely pass it along to our incoming qa folks. But similar to the doc tooling, the Addressables team doesn't have custom bug-reporting software that we can change as we desire. We have global tooling, and our small team has no knowledge or expertise surrounding how to change that tooling.


I wish I could be more helpful here. All in all, I think the git thing is clearly a bug, and clearly something we can poke at. If we can get it to repro :/

 

Yes, Unity is typically (nearly always) open when I pull. Generally that's not been a problem, I'll almost always have a clean working dir and at most I'll be prompted with the "scene has changed, reload?" dialog that I'm used to. In the past, the only times I've had issues pulling with Unity open is when we're migrating between versions, have asmdef changes, or have native plugin changes of any kind (ie those are situations where we notify the team so everyone knows to pull with Unity closed and/or to restart Unity after pulling).

If we need to close Unity to pull, I wasn't aware of that, and I'd hope it'd be remedied in the future -- we pull with relatively high-frequency, depending on the day & the bugs/issues resolved upstream.

Honestly I don't have the solution -- I know of solutions that have worked for me in organizations I've lead previously, but I was being paid to lead those organizations & teams! I was specifically paid to: identify issues, to discuss & ensure our teams understood them, and then to work with the teams to determine what solution(s) were plausible, and finally to make a decision on which solution(s) we would pursue.

In this case, I don't know the internal struggles and organizational challenges that exist -- it's clear to me that there are some, possibly many even, but I can't pinpoint them (though I've some guesses!) -- but that means it's awfully tough for me to prescribe "the fix". Not to mention, and with all due respect, I'm paying you guys -- not the other way around! The best I can really do is offer my advice from an external view, which is essentially offering up my "user story" and observations -- along with bitching when things are clearly broken and/or are costing my team time/money.

Some Suggestions / Thoughts / Guesses (with some passive-aggressiveness thrown in, for flavor):
Fair warning -- I'll start with the passive-aggressive! Though honestly it's not passive aggressive so much as it is legitimate & honest thoughts, and it comes from a place of genuine caring / concern for Unity's future (and by extension, for our own future, as we've invested heavily in the engine & are currently nearing release of our second relatively large-scale indie project).

• Where is the "[ops/eng.] leadership" in all this; the overall marketing stays the same, the demos are always great, but the nuts and bolts -- the core stuff -- it seems like the "shiny stuff" gets attention until it's "released" & then it's a struggle for mid-tier managers to get the needed time/resources to finish and continually improve things. My gut is the problems I see day-to-day stem from this very issue -- and I find it unlikely that individual devs are "the problem", and generally I believe you guys genuinely care and are quite competent.
  
  
• I was discussing this topic with an internal team-member the other day, specifically "leadership" vs the marketing vs the execution (ie "what does Unity's future look like"); to help me make a point during that discussion, I pulled up the Unity jobs page, and I had expected it to be pretty clear/obvious -- but it blew me away, it was exactly what I expected, but it went even further beyond my expectations than I'd have even imagined!! I had to laugh even, heh, but there are some... well let's just call them red-flags.
  • ~362 open positions.
  • ~50% are engineering roles.
  • ~25%(!!) are marketing/biz-dev
  • Of ALL positions ~17% have "manager" in the title.
  • Of Engineering positions only ~9.5% are "manager" titles.
  • There's more interesting/concerning data if you drill down further; but let's just say I want incredible asset loading & rock-solid graphics pipelines far before anything remotely related to AI, ML, Cloud, etc... =D =|
    
• Re: Bug Process
  Yes -- you need to make it trivially easy to submit bug reports, especially bug reports for big projects. If that means an SFTP server or something, so be it; don't waste your time on "cloud upload", just as I often tell small businesses not to build software until they outgrow Excel.
  
  
• Re: Bug Process
  Bugs should to be triaged rapidly and then prioritized accordingly.
  • There should be an "SLA-style" approach to the timing of bug triage, even if that's only internal/team performance metric to begin with, ideal world that'd be an externally visible metric.
  • Internally (and ideally externally), you should monitor the "mean time submission-to-fix" as a metric for each priority grouping, on a rolling basis.
    
  • IMO it's truly unacceptable for decent-to-good+ quality bug reports, especially those from paying customers, to be sitting for 2+ weeks before being looked at by a human.
  • The fastest way to get something fixed right now is getting the "right person's" attention via the forum, far and away. While that's not directly problematic itself, it's a pretty good indication that a systemic problem does indeed exist.
  • High priority bugs should be worked with actual high-priority, even if it's on an older system and the developer has since moved onto something more shiny (and likely more visible / promotable), so be it. I personally would guess issues here are prevalent, and it's a common issue across many orgs; the glory [and career progression] generally isn't in the trenches fixing bugs & improving years-old stuff, it's obviously in shipping the latest/greatest stuff for the never-ending keynotes. My experience, it's often a difficult problem to fix & often requires cultural 'shift', often from the leadership-levels & on down.
  • Bugs need to take priority over "features" in the vast majority of cases (exceptions do exist).
    
  • I occasionally am Googling (far too often frankly) and stumble on bugs on the public tracker that have been marked "fixed in 2019.x" and that have numerous 'comments' saying "still an issue in 2019x+". I doubt anyone at Unity is aware/gets notifications, either that or it's so rampant that they receive hundreds of notifications/noise kills the signal. That's clearly a systemic problem.
    
• Who IS responsible / empowered for the "systemic" problems?!
  Who is empowered to fix "Docs" issues / bug report processes / major systemic problems??
  • I hear you. You don't have the capability and/or aren't empowered with the responsibility and/or the resources to be able to fix some of these systemic issues. I get it. I also get that you genuinely care, and I respect that tremendously, and I appreciate it. It's also frustrating though, likely as much (or more) for you than for me, even. I think you care deeply about your area / 'your product' (ie Addressables), I think you're engaged, and you seem highly competent and capable of addressing issues within 'the product'. That's great, I appreciate it, and you're probably the type of developer we look for when we're hiring!
  • But who is actually capable of fixing systemic issues? Anyone?? Where's your manager, or your manager's manager? Who has the authority & is empowered, with the authority & the ability to allocate resources to actually enact systemic fixes / changes?!
  • It's even more ... concerning, because these problems generally/often impact the entirety of Unity ecosystem; meaning the value-proposition of fixing these systemic issues is incredibly good!! Indeed, I'd guess there are probably only a very select few projects that are at-or-above the value-proposition vs fixing these kinds of "systemic" problems. AI, ML, Cloud, all those buzzwords are worthless.
  • What we need is: high-quality, fully functioning foundational stuff, that's performant and extensible, that's documented/discoverable, that has good developer UX, and that is architecturally sound (ie meets requirements), and that is generally free of bugs -- and, importantly, these foundational elements MUST BE backed by high-quality, high-responsiveness processes to address real bugs that, even the absolute-best of developers, will inevitably introduce.
  • Any given 'product' can only be as good as the systems and processes that "surround" it; someone has to be empowered & responsible for those systems & processes. Otherwise even the most senior & highly-skilled developers will end up being held back by [from their perspective] these "external forces" and the overall product (and therefore dev UX, and Unity product itself) suffers and is directly limited.
  • Perhaps not the case, but I'll add -- if greater-than 1 individual is "ultimately responsible" for any 1 process/system, then that's nearly equivalent to no one being responsible. I don't know that it's the case here, but getting the impression that it might be.

Well, I spent way more time on this than I probably should have, and honestly that's part of the annoyance on my end here, too -- I'm paying Unity, not the other way around. While it may not be a massive monetary amount that we pay, by the same token the "consultation & external assessment" provided above is really not something I'd normally have paid for the privilege of providing -- indeed, typically it'd be the other way around!

Thank you for your time, and again I respect your engagement / interest and do think I generally understand your limited capability to "fix" some of this stuff -- ie I get it, you're not the problem, and you're doing all you can [and more, going above-and-beyond frankly]. I get it, and I hope some of the above may help in some small way but, unfortunately from where I sit, my ability to "fix" things is quite limited. Even my ability to evaluate/assess the root-cause of systemic problems is limited, and it means I'm left to making some educated guesses based on my observations & comparing the forward-facing problems to the issues I've had to solve in prior career experience. In any case, I do appreciate your time sincerely, and I know most of you devs care & are very passionate; frankly, I similarly wish that I could do more to help the Unity product get/stay/keep "on-track".

 

PS -- There's another Addressables bug we keep running into. See attached screenshot.

ISSUE:
The 'ResourceManagerCallbacks' continually ends up duplicating itself. Probably is an easy fix, or possibly user-error even, but I didn't dig around the source at all to find where it's instantiated or anything. Not sure what causes it to happen, but it happens frequently/continually, and occurs on both macOS and Windows editors & all devs have experienced it. We're all on 2019.3.15f1 currently.

For now, we've just been nuking the dupes. But this has been occurring for a while now, and we are on latest public release Addressables (as of last week at least, ie unless another version released since the bigger version release went up a week or two ago).

 

Agreeing a lot with Arthur here. Not so much experience with bug reports, (but again this may be part of the issue : I've been using unity daily for 10 years now, and I have actually sent out only 5 bug reports), but documentation is an issue I'm facing a lot, especially more so now that a lot of subsystem are pulled into packages.
Basically features are now hidden from the main documentation, which makes sense as it's in a package and not the main product, but hurts the user experience since we no longer have a unified, searchable source for documentation. So maybe the main documentation should have links to the packagfes documentations.

But my main point is on actual documentation and that's where your team can make improvements, or at least the technical writer you have access to : lately there's been a push it seems in documentation coverage using automated documentation. Meaning all API is covered with nice tables with method name and return types. It's all fine and well, but it's just useless as is if there's no more details and examples.
Basically, if I get no more info by searching the documentation that I would get by firing up Intellisense, then you're just wasting my time making me search and believe I'll get infos.

To your credit though I couldn't find quickly and example of just that in the curent Adressable documentation, there's always at least a short explanation on the meaning of the variables, but it's still laking in details and examples.

 

I agree with all of Arthur's rants. I've been feeling similar myself, but I typically keep my rants offline. I also happen to be one of those people that comments on a "fixed" bug that wasn't actually fixed.

It would probably also help if we had a place to actually put feedback like this, rather than in a package-specific forum (of course, this seems to be one of the more active forums in terms of dev responses compared to other forums) or General where it will just get drowned out immediately.