|
Love Stole the Day posted:imo if your organization is so Boy, do we!
|
#
?
Apr 19, 2024 16:06
|
|
|
|
| # ? May 3, 2024 08:17 |
|
|
Honestly, switch to GraphQL and use self-documenting API's?
|
|
#
?
Apr 19, 2024 16:14
|
|
|
We just finished a project for autogenerated documentation where we pull the readme, input and output info, tests, and changelog and turn it all into a wiki page the end result looks pretty good, all the different items are in one place, and the tests are turned into code examples this is for a library of internal facing terraform modules
|
|
#
?
Apr 19, 2024 16:24
|
|
|
kayakyakr posted:Honestly, switch to GraphQL and use self-documenting API's? The complexity for us is that boundaries are not well defined, we stuff things in request specific contexts and get/update those throughout the lifecycle of a request, with absolutely no well defined interfaces. The positive is my team can hoist stuff out easier than most and my new incoming manager is really passionate about stuff like this. The negative is my company is old guard red tape middling managers who love toil.
|
|
#
?
Apr 19, 2024 16:27
|
|
|
The Fool posted:We just finished a project for autogenerated documentation where we pull the readme, input and output info, tests, and changelog and turn it all into a wiki page Auto generated documentation has been suggested as an alternative, but it's a vicious cycle of no priority being given to setting it up, the person responsible is pulled on to something else, the project stagnates and dies, and then the next time auto generated documentation is suggested my counterpart has a new hotness solution that he also gets bored of and abandons after a while.
|
|
#
?
Apr 19, 2024 16:39
|
|
|
Yeah, this was our third attempt at it over the last two years for exactly those reasons. Just luck that we were able to avoid distraction/reprioritization long enough to get it over the line.
|
|
#
?
Apr 19, 2024 17:07
|
|
|
If there's four possible locations for varying-correctness documentation then consulting them will be my last resort because that is a pain in the rear end. If there's one location and it's not wrong (and I remember that it exists), I might check it before just reading the code or poking the endpoint or calling functions that look relevant to see what happens. So my suggestion is to delete all the sources of incorrect documentation before you embark on the one true source. And if you get distracted after the deletion step, you've still made my day faster as the schlub who no longer has four possible locations to check. "But there might be something important in the wrong documentation!" well you were just saying how useless your documentation is so no, there isn't. But ok then download an archive, put a .zip somewhere, and never look at it. Pay for its storage with the savings from having fewer Notion seats or whatever.
|
|
#
?
Apr 19, 2024 17:40
|
|
|
I wanna tattoo all that on my face. Why do docs work for us now? Because I told my manager - the old "TL" can't share knowledge in a way that allows engineers to grow, I need some time to improve this - and he said "cool rebuild the knowledge base" and instead of relying on lovely old docs I just blasted some Celsius and read the code myself, then made structured pages that let engineers jump in and guide them in understanding things and point to structure that won't change without massive refactors but leave the line by line understanding to them.
|
|
#
?
Apr 19, 2024 19:23
|
|
|
Love Stole the Day posted:imo if your organization is so that's right
|
|
#
?
Apr 19, 2024 19:40
|
|
|
Sadly the official line is "it's his team and he can run it however he wants" even though it negatively affects other teams including mine in visible and measurable ways. Fortunately we were recently acquired and the new big wigs are pushing hard for things like process, documentation, and predictable delivery so at least I have some help from above now.
|
|
#
?
Apr 19, 2024 19:41
|
|
|
Ensign Expendable posted:Sadly the official line is "it's his team and he can run it however he wants" even though it negatively affects other teams including mine in visible and measurable ways. lol i have this but "however he wants" includes making GBS threads all over my team's projects because ownership of features/modules is undeclared and conceptually shared through the entire org
|
|
#
?
Apr 19, 2024 19:53
|
|
|
leper khan posted:lol i have this but "however he wants" includes making GBS threads all over my team's projects because ownership of features/modules is undeclared and conceptually shared through the entire org The feature is blocked because the code review I submitted 15 minutes ago for it to you hasn't been approved yet. Your manager will be asking shortly when you're going to approve it. Edit: The pull request doesn't even compile.
|
|
#
?
Apr 20, 2024 01:46
|
|
|
We went heavy on DDD (the useful parts) for my latest project and it turned out really well. Basically banned documenting things in places like Confluence and people gradually got really comfortable with spending a few extra minutes coming up with appropriate names for things and being defensive of our domain without bikeshedding. The type system is leaned on hard - we use a lot of sealed classes and custom-built things like a NonEmptyList<T>, and we try to encode as much business logic as we can into types. This also has the benefit of making it easy to put almost all business logic in a functionally pure module. Our documents are pretty much just an event storming diagram, the code, and a few integration/flow charts to understand more complex behavior. Documenting the accidental complexity seems to be the part that really sucks and that no one wants to maintain.
|
|
#
?
Apr 20, 2024 03:59
|
|
|
auto-generated docs are fuckin useless tbhkayakyakr posted:Honestly, switch to GraphQL and use self-documenting API's? 
|
|
#
?
Apr 20, 2024 04:19
|
|
|
I’m starting to like a tiny bit the JSDoc/TSDoc poo poo show that VSCode supports, ie bare minimum to provide some annotations in the UI. But it’s not remotely great, especially with inline examples that usually take up a lot of screen real estate.
|
|
#
?
Apr 20, 2024 05:42
|
|
|
Auto-generated documentation rarely, if ever, document the non-obvious stuff. It's useful only in the "we're required to document stuff and this saves us time" sense.
|
|
#
?
Apr 20, 2024 14:30
|
|
|
One of the engineers where I work built an auto documentation tool that displays the syntax for all the REST APIs, both what counts as a valid message and examples of what will be returned. It has been enormously helpful and a huge time saver.
|
|
#
?
Apr 20, 2024 14:51
|
|
|
is that not just swagger?
|
|
#
?
Apr 20, 2024 14:57
|
|
|
The Fool posted:is that not just swagger? Actually yes. I didn't realize that was a well-known tool. Everyone at work talks about it like it is a custom tool. That's pretty funny, he took credit for making something that's an open source tool. He's not even a contributor as far as I can tell. LLSix fucked around with this message at 15:53 on Apr 20, 2024 |
|
#
?
Apr 20, 2024 15:50
|
|
|
lmao, good on him I have no idea what the lift is to get swagger into an established code base but I've done a number of projects with fastapi and it has swagger built in and it is really nice having that stuff from the start
|
|
#
?
Apr 20, 2024 16:06
|
|
|
We got some weird thing that spits out Postman collections. Great in practice, but while it gives you the variable names it doesn't give you the types. Every primitive has "Lorem ipsum" in the example payload, and only the first level nested objects are rendered. There are also no comments to help you figure out what each field is actually for or any other behavior of the system. It's about as useful as you can imagine but it serves the purpose of being able to say "we got you your documentation, now piss off".
|
|
#
?
Apr 20, 2024 16:14
|
|
|
I don’t know what…anything…you’re using, but a lot of these things let you annotate functions and parameters with better typing and better input and output examples for Postman and OpenAPI.
|
|
#
?
Apr 20, 2024 16:31
|
|
|
Just feed your entire codebase into chatgpt and ask it to write docs.
|
|
#
?
Apr 20, 2024 17:36
|
|
|
if I wanted my docs to be wrong I'd let marketing write them
|
|
#
?
Apr 20, 2024 17:37
|
|
|
The Fool posted:lmao, good on him It's usually 1 or 2 lines of code. Maybe more work if you want docs for like web sockets and such.
|
|
#
?
Apr 20, 2024 17:43
|
|
|
Plorkyeran posted:Just feed your entire codebase into chatgpt and ask it to write docs. This works surprisingly well for copilot for the boilerplate stuff if you give it about a paragraph to work from
|
|
#
?
Apr 20, 2024 17:51
|
|
|
If you're using a framework of some kind (like RestControllers in Spring) I think you just add the dependency and it will autoconfigure most stuff. You can definitely mess around more to make it better, and it doesn't necessarily work out of the box if you have other libraries that provide their own endpoints.
|
|
#
?
Apr 20, 2024 18:04
|
|
|
it's pretty hard to integrate swagger into a system that doesn't have typed response objects, and can be hard to get swagger to fully document things like different error responses. this probably won't matter that much unless you are trying to use client generation we've got a really weird system at work... basically like 30+ java/kotlin services that use swagger but kind of poorly, and they have a confusing mix of internal and external endpoints. the external endpoints get mapped arbitrarily through an nginx proxy so we can't really generate external-facing clients. we're moving to grpc for internal stuff, which seems fine. the weird thing now is that we're experimenting with using protobufs to define external-facing http resources as well, which i'd be into if protobuf wasn't an incredibly loving wack serialization format that was made to express distributed function arguments and not, like, an external-facing API contract. you also still need to manually define an http client for your endpoints in this situation, you just get the advantage of generated code for request/response bodies. i've been mulling over this situation and i've been thinking about trying to back us out of using protobufs for defining http resources and going in on using swagger, but we'd need to centralize our external-facing endpoints into a single routing table that swagger understands to really get full advantage of that. we already use a backend-for-frontend service for some stuff so we might just start generating a client purely for that service, and then start trying to move everything external there? however our BFF service was never really intended to scale up that large (architecturally, that is: from a performance perspective it is very easy to scale a node http service that does nothing but calls to other services) so that's it's own can of worms
|
|
#
?
Apr 20, 2024 18:33
|
|
|
thotsky posted:Auto-generated documentation rarely, if ever, document the non-obvious stuff. It's useful only in the "we're required to document stuff and this saves us time" sense.
|
|
#
?
Apr 20, 2024 19:00
|
|
|
Vulture Culture posted:Auto-generated docs usually document non-obvious stuff fine in the essential complexity lane and poorly in the incidental complexity lane. This is actually the exact forcing function you want; if your docs are insufficient, it's because your code modeling of your domain is bad and you need to fix it Too long to get as a tattoo unfortunately...
|
|
#
?
Apr 20, 2024 19:43
|
|
|
Plorkyeran posted:Just feed your entire codebase into chatgpt and ask it to write docs. i couldnt even get chatgpt to use a function pointer correctly. lol at using it for literally anything
|
|
#
?
Apr 20, 2024 19:52
|
|
|
Vulture Culture posted:Auto-generated docs usually document non-obvious stuff fine in the essential complexity lane and poorly in the incidental complexity lane. This is actually the exact forcing function you want; if your docs are insufficient, it's because your code modeling of your domain is bad and you need to fix it I don't understand how autogenerated docs lean either direction. I'm assuming autogenerated means pulling comments from above types and functions, maybe I'm misunderstanding. But I don't see why people would be more likely to comment about essential versus incidental complexity. If anything, I'd expect the incidental complexity to make it harder to find the explanations of relevant essential complexity. Like "oh yeah you gotta use ProxyThingImpl in code but the reason why is explained on IdealThing".
|
|
#
?
Apr 20, 2024 20:38
|
|
|
pokeyman posted:I don't understand how autogenerated docs lean either direction. I'm assuming autogenerated means pulling comments from above types and functions, maybe I'm misunderstanding. But I don't see why people would be more likely to comment about essential versus incidental complexity. If anything, I'd expect the incidental complexity to make it harder to find the explanations of relevant essential complexity. Like "oh yeah you gotta use ProxyThingImpl in code but the reason why is explained on IdealThing". While waiting for VC's take.. I've been finding that when the code models the domain well, there's less opportunity for useful comments.The comments never explain why you made your whole database schema a domain aggregate, or why you can mutate the same data 4 different ways in 6 different microservices. Those are the things that impact ability to scale, maintain, and reason about your system. Generated docs can help me understand the flow of bytes from class to class, but I typically don't need help with that if things are named well.
|
|
#
?
Apr 20, 2024 20:54
|
|
|
pokeyman posted:I don't understand how autogenerated docs lean either direction. I'm assuming autogenerated means pulling comments from above types and functions, maybe I'm misunderstanding. But I don't see why people would be more likely to comment about essential versus incidental complexity. If anything, I'd expect the incidental complexity to make it harder to find the explanations of relevant essential complexity. Like "oh yeah you gotta use ProxyThingImpl in code but the reason why is explained on IdealThing". I mean Swagger/OpenAPI and stuff like that more than JavaDoc. JavaDoc is just the documentation living in the code and then being stitched together by a process. It's still written by humans which has its own downsides. I guess JavaDoc with no actual comments in it might also be what I'm talking about. For example, Swagger docs are useless if the API talks to an underlying system with its own syntax and logic. Say, you have a custom query language for a proprietary database but you use REST endpoints to send them. Most .NET function documentation to me seems pretty useless as it just lists a bunch of types and arguments, but rarely say anything about how to use them and why.
|
|
#
?
Apr 20, 2024 22:11
|
|
|
Oh I see, that makes more sense.
|
|
#
?
Apr 20, 2024 22:30
|
|
|
SMH if you need to touch network in your code.
|
|
#
?
Apr 21, 2024 09:05
|
|
|
thotsky posted:For example, Swagger docs are useless if the API talks to an underlying system with its own syntax and logic. Yeah we have notes in our code that regularly explain nuances of other auth flows on the data we process because it's impossible to know everything from them unless you built them. It's an organziational and modeling failure but saying that doesn't do much vs. simply docing our code slightly better.
|
|
#
?
Apr 21, 2024 16:20
|
|
|
I think y'all got the gist of what I was saying, but I want to add this: sometimes your code can feel poorly-documented if it's really your domain that's poorly-understood (with poor documentation being one common reason that happens). As an example: if you've never worked on SSO and you're suddenly thrown into the middle of trying to diagnose a problem in an OAuth 2.0 flow, you will get very frustrated by a complete lack of comments. If you've written a basic IdP before, you'll probably follow the flow of anyone else's implementation pretty easily, comments or not, because you know what to expect even if you don't find exactly that. It's really crucial for the domain to have great documentation, and then code comments become largely hygienic: the code should map in obvious ways to the parts of the domain you've documented. (Like all outliers, document the poo poo out of the parts that don't.) Incidentally: if you try this and find you don't have a domain complex enough to be worth documenting, don't write the loving microservice. Vulture Culture fucked around with this message at 15:51 on Apr 22, 2024 |
|
#
?
Apr 22, 2024 15:29
|
|
|
For my team, complexity comes from operating at varying degrees within our IdP. Pre-auth, during-auth, and post-auth are all things we build features around. We have tons of data points that we fetch in a request flow based on network info, a policy configuration, the IP address, user's behavior, tons of things. Thus the complexity comes in a few pieces: how do we feed these points into a system and decision on them, where do we allow varying degrees of configuration based on what clients what, and at what point/in what factors, contexts, etc do we support enforcement? quote:
|
|
#
?
Apr 22, 2024 16:39
|
|
|
|
| # ? May 3, 2024 08:17 |
|
|
Bojack Srcmain posted:For my team, complexity comes from operating at varying degrees within our IdP. Pre-auth, during-auth, and post-auth are all things we build features around. We have tons of data points that we fetch in a request flow based on network info, a policy configuration, the IP address, user's behavior, tons of things. Thus the complexity comes in a few pieces: how do we feed these points into a system and decision on them, where do we allow varying degrees of configuration based on what clients what, and at what point/in what factors, contexts, etc do we support enforcement? In this case, the leaky domain abstractions are that a) a source of truth doesn't really exist, and b) many capabilities/properties attached to the request context are ambient rather than explicit Vulture Culture fucked around with this message at 01:15 on Apr 23, 2024 |
|
#
?
Apr 23, 2024 01:13
|
|