My team has been using swashbuckle in the dotnet API ecosystem which generates an open-api document based on your code, commemts and c# attributes (for the things it can't infer from the former). The documentation and code have a symbiotic relationship.
I work at an organization where we build mostly internally used tools to support different products/service lines. Here's what I've been advocating for and it works fairly well without requiring a lot of time to write documentation that is, often out of date. I find mileage varies as some people always just ask a senior engineer and never look at the documentation.
We have a high level wiki page about each application/micro service we support. Things like
- resource locations
- job schedules, purposes, inputs/outputs
-FAQ's
- known dependencies on other micro services, etc
We also have wiki pages for
- onboarding
- team norms and expectations (pr process, on-call duties, coding conventions, etc)
Inside each application's or micro service's repo the readme should have steps to
- get the project running locally.
- document feature flags
- document conventions unique to that project
- document how to trigger a release
Someone here said the code should be the source of truth and other documentation isn't needed. To me it's unclear what they mean by that exactly; I could get behind that if they are documenting via comments on functions/classes/etc. my org tends to not write much comments in the code so it's really hard to tell if the code does what it was intended to do or if there is a bug. What I love to see for "self documenting" code is tests. You write tests to either test for outcomes you expect or test outcomes that you don't expect, don't happen.
I've been using blazor since release in 2019 and can count on one hand the amount of times a call to StateHasChanged() was used and actually needed when doing a peer review
Most of the time I've seen that function used it was due to improperly written asynchronous code.
if you havent used blazor before there are some downsides.
The developer experience with blazor is lacking.
Debugging tools aren't up to par with other dotnet SDKs.
Hot reload only works when not debugging and only if you don't modify member signatures and a plethora of other conditions.
Because of the afore mentioned the feedback loop during development can be slow.
The razor editor doesn't support all the helpful actions you're used to with dotnet (e.g. cleaning up unused imports).
Sometimes the razor editor gives really bizarre errors and you simply need to close Visual Studio and reopen for the. tk disappear
I dont mind the framework itself but there's a few design decisions that could have been better.
I think there are some good use cases for it though. AOT compilation to wasm is kinda neat for workloads that may benefit from that.
I also think that blazor server might just be the most novice friendly way to get I to web development because it abstracts away much of the web. that being said, the blazor server architecture has a plethora of drawbacks.
For me switching playback device is quick and reliable if the device is a PC or phone. Whenever I try to select a connected Google speaker... it takes like 3-5 tries. I've found it is more reliable to use voice commands to get the speaker to play Spotify then I can use a phone/PC to select the song/playlist/podcast/etc. but it's kind of frustrating it just doesn't work well to begin with.
I went to a Gartner conference one year because my work paid for it. RIP my work inbox ever since. my email has been sold and sold over and over again.
Gartner tells you what you probably already knew them sells your information.
My team has been using swashbuckle in the dotnet API ecosystem which generates an open-api document based on your code, commemts and c# attributes (for the things it can't infer from the former). The documentation and code have a symbiotic relationship.