|
Yeah, it's good to document what you need to do, even when all you need to do is the extremely simple and normal obvious thing.
|
#
?
Nov 12, 2023 06:26
|
|
|
|
| # ? May 9, 2024 23:48 |
|
|
Bongo Bill posted:Yeah, it's good to document what you need to do, even when all you need to do is the extremely simple and normal obvious thing. Yeah, adding onto this. It also speeds up onboarding folks who might be familiar with the language, but aren't familiar with the specific toolset you're using (or may have been working somewhere with weird environment setups before).
|
|
#
?
Nov 12, 2023 07:55
|
|
|
But why are these instructions not in the README.md file at the root of the repository? Always document these steps, however trivial they seem, but put them somewhere people will instantly find them when they open the project.
|
|
#
?
Nov 12, 2023 11:56
|
|
|
"Where is that documented?" is how we insult each other, in Large Organizations
|
|
#
?
Nov 12, 2023 13:42
|
|
|
Apoffys posted:But why are these instructions not in the README.md file at the root of the repository?
|
|
#
?
Nov 12, 2023 13:47
|
|
|
Apoffys posted:But why are these instructions not in the README.md file at the root of the repository? yeah this. get these instructions in a text file of some kind in the place that the instructions apply to. IMO, the instructions should have - Explicit instructions with copy-pastable commands to install the language runtime(s) you need or version managers (nvm, asdf, whatever) to install the language runtimes you need - Explicit instructions with copy-pastable commands to install the dev dependencies And you should strongly consider having those copy-pastable commands in a script especially if it's a multi-language setup.
|
|
#
?
Nov 12, 2023 13:49
|
|
|
M31 posted:This is some coping mechanism in action right? As someone who works in a lot of different languages and dev contexts I always really appreciate it. Sure, duh, package.json = run npm, but if I've been off in c++ land for a while i have to rerail my brain to think of that, and then of course keep in mind that if theres a yarn.lock in addition to package.json actually it's a yarn project, if it's a desktop setup thing there may need to be some other setup, maybe there's actually a docker environment for this, etc etc
|
|
#
?
Nov 12, 2023 13:52
|
|
|
Congrats on having coworkers that read them I guess. I get to point devs to their own repositories readme at least once a week.
|
|
#
?
Nov 12, 2023 14:07
|
|
|
M31 posted:This is some coping mechanism in action right? Kind of, I guess? The idiot who needs this explicit, detailed README is usually me when I come back to a repo I haven't touched in months.
|
|
#
?
Nov 12, 2023 14:31
|
|
|
Apoffys posted:Kind of, I guess? Write the document for the idiot you will be in 6 months is a great standard for documentation. Keeping it in a readme vs a wiki/confluence, there a pros and cons for each way. It is criminal to keeping this document in Word in an ISO folder next to the dress code and outdated presentation templates.
|
|
#
?
Nov 12, 2023 15:03
|
|
|
Love Stole the Day posted:"Where is that documented?" is how we insult each other, in Large Organizations Right up there with, “was there a story for this?”
|
|
#
?
Nov 12, 2023 15:06
|
|
|
Falcon2001 posted:Yeah, adding onto this. It also speeds up onboarding folks who might be familiar with the language, but aren't familiar with the specific toolset you're using (or may have been working somewhere with weird environment setups before). And you can get them to update it to what they actually need to do as part of their onboarding.
|
|
#
?
Nov 12, 2023 15:43
|
|
|
ultrafilter posted:And you can get them to update it to what they actually need to do as part of their onboarding. This is actually an excellent technique for handling drift between documentation and reality.
|
|
#
?
Nov 12, 2023 17:04
|
|
|
Also it's like 99% easier to say "oh the setup stuff is in the readme [link]" than "uhh let me go find that on the wiki,"
|
|
#
?
Nov 12, 2023 17:58
|
|
|
Like backups, if you've never restored from backups, you don't have backups. If you've never onboarded someone using your documentation, you don't have documentation.
|
|
#
?
Nov 12, 2023 18:13
|
|
|
Phobeste posted:Also it's like 99% easier to say "oh the setup stuff is in the readme [link]" than "uhh let me go find that on the wiki," Yeah but the wiki will often have better tools for editing and viewing, "finding it on the wiki" is like 45 seconds of using the Search bar, and it lets you search everywhere for "what projects use CMake". There are other benefits to using a readme, either way could be fine depending on specifics.
|
|
#
?
Nov 12, 2023 18:28
|
|
|
We'll just set up a process to scrape the Readmes into the wiki. This will absolutely not be brittle and half-rear end.
|
|
#
?
Nov 12, 2023 18:38
|
|
|
We've been using Backstage TechDocs to collect documentation from GitHub, confluence, and Google docs. Over the years we had things maintained in disparate places and this gets them all in one place, which has been hugely beneficial. Some of our more complex code has a multi-directory docs folder with everything from system architecture diagrams to operations run books.
|
|
#
?
Nov 12, 2023 18:38
|
|
|
Apoffys posted:But why are these instructions not in the README.md file at the root of the repository? I should mention in context of my VP that those instructions were absolutely in the README.md file last updated 7 months ago, he is just *that* incompetent, or unwilling to actually open the repository and look at it himself at any point since he has been hired 
Macichne Leainig fucked around with this message at 18:49 on Nov 12, 2023 |
|
#
?
Nov 12, 2023 18:46
|
|
|
Macichne Leainig posted:I should mention in context of my VP that those instructions were absolutely in the README.md file last updated 7 months ago, he is just *that* incompetent, or unwilling to actually open the repository and look at it himself at any point since he has been hired He was hired to lead, not to read.
|
|
#
?
Nov 12, 2023 18:49
|
|
|
MajorBonnet posted:He was hired to lead, not to read. I have bad news about the nature of the email and Slack responses I have sent to him then
|
|
#
?
Nov 12, 2023 18:54
|
|
|
Yeah, many of my team's packages have a default README.md that came with our internal build system and I'm constantly trying to find time to update it to include at least a basic 'here's what this loving package does'. (or update stuff as it becomes inaccurate) I wouldn't personally put that stuff into a wiki unless there was a need for more context, but I like to use DEVELOPMENT.md as a sort of 'quick guide for getting a dev environment setup locally, only making assumptions of knowledge that I can safely make or are documented elsewhere'. Vaguely related, but I'm the target of a knowledge transfer for a process that has been handled by another site for at least five years and the amoung of stuff they assumed was common knowledge and is in fact weird esoterica or undocumented human heuristics is high enough to be concerning even if it isn't surprising. You can overdocument things, there's definitely an art to it, but all the comments in here like these: CPColin posted:Like backups, if you've never restored from backups, you don't have backups. If you've never onboarded someone using your documentation, you don't have documentation. Volmarias posted:This is actually an excellent technique for handling drift between documentation and reality. These are 900% accurate.
|
|
#
?
Nov 12, 2023 19:33
|
|
|
Developer docs belong in a markdown file in your repo, and that's a hill I am 100% willing to die on. At my current place we are instead pushed to use Notion and you can see the drop in quality between the in-repo docs and Notion docs when it comes to being kept up to date. It is also much harder to correlate what version of the code the docs were written for, with the actual code.
|
|
#
?
Nov 12, 2023 23:58
|
|
|
I recently found this and it’s an interesting idea for setup and runbooks, and ties together documentation and scripts pretty well. https://runme.dev/
|
|
#
?
Nov 13, 2023 00:30
|
|
|
Nybble posted:I recently found this and it’s an interesting idea for setup and runbooks, and ties together documentation and scripts pretty well. https://runme.dev/
|
|
#
?
Nov 13, 2023 17:05
|
|
|
Vulture Culture posted:As someone who's mostly lived in Python the last few years, this feels like a more limited Jupyter notebook Or something that I'd use the obsidian.md plugin 'execute code' with.
|
|
#
?
Nov 13, 2023 20:57
|
|
|
Vulture Culture posted:As someone who's mostly lived in Python the last few years, this feels like a more limited Jupyter notebook Yeah, the Jupyter vscode extension is pretty solid
|
|
#
?
Nov 13, 2023 23:43
|
|
|
The Fool posted:Yeah, the Jupyter vscode extension is pretty solid
|
|
#
?
Nov 15, 2023 21:15
|
|
|
If you have a monorepo, what do you do with code for a service that is decommissioned? Normally I would just archive the repo in GitHub but that doesn’t work here.
|
|
#
?
Nov 17, 2023 23:27
|
|
|
Try to delete it, see that even though the service is unused, it's still load bearing, and then shelve it and not touch it for 10 years in my experience
|
|
#
?
Nov 17, 2023 23:38
|
|
|
smackfu posted:If you have a monorepo, what do you do with code for a service that is decommissioned? Normally I would just archive the repo in GitHub but that doesn’t work here. You just delete it? It's still there in the revision history if someone needs to inspect the old code.
|
|
#
?
Nov 18, 2023 00:29
|
|
|
smackfu posted:If you have a monorepo, what do you do with code for a service that is decommissioned? Normally I would just archive the repo in GitHub but that doesn’t work here. Delete it and keep track of the commit somewhere in the event of: Macichne Leainig posted:Try to delete it, see that even though the service is unused, it's still load bearing, and then shelve it and not touch it for 10 years in my experience Yeah. I usually try to have a CI job that goes through and attempts to build/test all services in the monorepo that depend on a service that is being changed to try and catch those sorts of things but there's always weird edge cases
|
|
#
?
Nov 18, 2023 00:33
|
|
|
Jabor posted:You just delete it? It's still there in the revision history if someone needs to inspect the old code. It's this if you're lucky, otherwise Macichne Leainig posted:Try to delete it, see that even though the service is unused, it's still load bearing, and then shelve it and not touch it for 10 years in my experience
|
|
#
?
Nov 18, 2023 08:41
|
|
|
smackfu posted:If you have a monorepo, what do you do with code for a service that is decommissioned? Normally I would just archive the repo in GitHub but that doesn’t work here.
|
|
#
?
Nov 18, 2023 22:29
|
|
|
My ticket: The tiny hard drive you gave me is full of compilers and libraries. AppData is taking up 40% of the drive with DLLs. Please clone me to a larger drive. IT: How about you reinstall all your development environments to the D drive instead?
|
|
#
?
Nov 18, 2023 23:26
|
|
|
Cup Runneth Over posted:My ticket: The tiny hard drive you gave me is full of compilers and libraries. AppData is taking up 40% of the drive with DLLs. Please clone me to a larger drive.
|
|
#
?
Nov 20, 2023 16:38
|
|
|
Reply: I got a D drive for ya
|
|
#
?
Nov 20, 2023 16:42
|
|
|
My company has grown a lot in the last few years and we've picked up a few real live "business people". People who wear suits, have MBAs, and entire resume consists of job titles that start with 'C'. A few are okay, but oof, dealing with most of them is painful. For example, in our particular niche there is a process that, if you weren't familiar with the field, would seem easily automated. Like full self driving, it's something that's so context dependent that automation could only work for the most spherical version of the problem. This hasn't stopped a bunch of companies from popping up promising that their use of AI nonsense has finally let them crack it. These companies invariably can't keep customers and either fold or pivot to something else. Despite the large pile of corpse surrounding it, a couple members of senior leadership have decided that we, being the protagonists of this story, will be the ones to solve the problem. I just had this interaction: Them: We need you to estimate how long it'd take the dev team to implement *some company's algorithm to automate desirable thing* from scratch Me: Why? Our analysis has indicated that their algorithm isn't very good and that's backed by what we know about their customer churn Them: We're doing a build vs. buy exercise Me: And? Them: And we need to know how close we'll get to *impractical dream offering that requires AGI and time travel* if we acquire their company Me: Given that we don't think it works, it probably won't get us meaningfully closer to *dream goal* Them: Right, so we also need as estimate for how long it'd take the dev team to make the algorithm work for *dream goal* if we acquired their company Me: Do you have some source of information or insight beyond what we've already figured out? Them: No. Can you have an estimate for how many quarters both would take by tomorrow morning? We're making a slide deck to present to the board Me:  Part of me thinks I should estimate 15 minutes because just outputting a bunch of random numbers would probably be pretty close and be received about as well by our customers.
|
|
#
?
Nov 28, 2023 21:47
|
|
|
steckles posted:Them: We need you to estimate how long it'd take the dev team to implement *some company's algorithm to automate desirable thing* from scratch Make a spike user story on the technical feasibility of implementing x, and postpone your estimate until completing that user story. Spend the sprint researching the problem, solutions, why it would/wouldn't work. If you deny it immediately, you'll give the impression of being difficult, if you spend two weeks researching the scope of the problem and detailing what would need to be solved, you look more informed. Who knows, maybe you'll hit on a better way of solving the problem, or an incremental solution that doesn't solve the problem but builds towards the solution later, and can at least be estimated. Better to have the documentation of "these problems would need to be solved in order for us to proceed with this solution" explicitly written rather than making the assumption they have common sense.
|
|
#
?
Nov 28, 2023 23:02
|
|
|
|
| # ? May 9, 2024 23:48 |
|
|
Generally speaking, don't put yourself in the position of telling a C-level what is or is not an acceptable business risk unless they have hired you to do that job. Use this as a learning opportunity to figure out what assumptions you've been taking for granted while speaking to other technical experts, and figure out how to make those known to "the business" without teaching them how to do your whole job Surface the top three to five risks, quantify them as best you can, and propose a militantly awful solution that involves taking engineers from several revenue-generating product lines so you can get all the business's tech directors to do the hard part of this for you. No reason this situation should fall on your shoulders alone
|
|
#
?
Nov 28, 2023 23:44
|
|