|
Love Stole the Day posted:imo if your organization is so Boy, do we!
|
#
?
Apr 19, 2024 16:06
|
|
|
|
| # ? Apr 20, 2024 11:27 |
|
|
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
|
|
|
|
| # ? Apr 20, 2024 11:27 |
|
|
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
|
|
