3 ms·
> We'll get the job done without her, but it'll take us 5×? 10×? as long. This begs further reflection. Is it because Alice was amazing? Is it because the cod
by andsoitis 4y ago
> We'll get the job done without her, but it'll take us 5×? 10×? as long.
This begs further reflection.
Is it because Alice was amazing? Is it because the code is bad? Is it that the other engineers aren’t seasoned enough? Maybe that system is badly implemented.
Also, people leave all the time so you have to be ok with an Alice leaving (or die). You cannot depend on people being around for ever to ensure continuity.
- agent281 4y agoSometimes places have high turn over because they ask people to move fast while cutting corners because have high turn over and don't know how long people will be there and so they ask people to move fast while cutting corners because they have high turn over...
- tgsovlerkhgsel 4y agoNo, it's because people who have a lot of experience with one thing tend to be better at that thing, regardless of how good your documentation is.
- justin_oaks 4y agoIt's like levels of caching. Having information in someone's head is like having it in an L1/L2 cache. Having documentation is like having the information in RAM. And having no documentation and putting things together from scratch is like hitting a hard drive.
- toyg 4y agoThat's an amazing similitude, I must note it down. I reckon the last bit could be even "got to fetch it from the network", since you'll likely have to hit Stack overflow..
- bsurmanski 4y agoTo stretch out the metaphor, asking a knowledgeable coworker could be "read from RAM", then documentation could be "read from disk"; or vice versa. But I find having someone to bounce questions off of easier than reading docs
- waltbosz 4y agoI'm leaving a role where I've been the sole supporter for 5 years of a Windows app written by amateurs. Every antipattern you can imagine if in there. I compare it to a maze that I've traveled many times. I know my way around the maze, but I don't think the team that I'm KTing this too is going to figure it out. I predict they're going to just freeze the code and leave any existing bugs as is.
- justin_oaks 4y agoGenerally it's because nothing is documented. All the knowledge about a system is in the previous employee's head. Now it all has to be pieced together from what code and configuration exists. Nobody documented the shortcuts, the rationale for why it is coded/configured that way, or the quirks or bugs in the system. Of course none of this can be put into a spreadsheet thus it doesn't exist, as far as management is concerned.
- gscott 4y agoThere is no real way to document a large software system even if you wanted to. You would have to update the documentation every day assuming someone is going to read and digest it even if you make it available.
- ckolkey 4y agoIt was because Alice had experience and familiarity with it, which was lost when she left.
- schmorptron 4y agoSo the answer to GP's point "Also, people leave all the time so you have to be ok with an Alice leaving (or die). You cannot depend on people being around for ever to ensure continuity." would be that if the trend was for people to be rewarded for sticking around longer, even if alice quit there would on average still be a Bob or an Eve with the same level of experience in the team who could hanlde this?
- watwut 4y agoIt is because Alice knows the code, so she does not have to spend time figuring it out. It is because Alice knows what was important requirement and what was emergent property, so she knows what she can sacrifice. It is because Alice knows how to log in, where to click to get to the right place and what to fill into fields to enable the button.
- forgotusername6 4y agoSure, someone can do it. But Alice had spent several months becoming an expert on that particular part of the software. She knew the domain, had good contacts with the micro-service owners, knew the API off by heart and of course she wrote the code. All of that can be learnt again but it will take another few months. Now the feature that would have taken a weak takes seven weeks. Would it have been cost effective to have two engineers becoming experts at the same time in case Alice left? No. Will he carefully written docs she left help? Maybe, but until we have another expert on that feature, every modification will take much longer.
- deathanatos 4y agoI thought about remarking on documentation, but I wanted to keep the comment brief. Even where we have documentation, what experience buys you — what Alice in the example has — is that she's going to the documentation to spur her memory, as a quick double check, and just to give her a good guide rail to make sure she hasn't missed anything. But because she knows the area, she can still be quick about it. Someone new to the system are stuck using the docs not for reference, but for tutorial and basic understanding. They're going to need to read every word, and worse, comprehend every word, and that will take far, far more effort than the "I'm a bit foggy on detail D, what did the docs say? Oh right." that Alice would be doing. But let's accept your "Maybe that the system is badly implentmented" — quite possibly! But it's the experience of having worked with it, learned how it modeled its problem, and learned how its model falls down and then, finally, that insight into "this would be a better way". That takes time and understanding, if you want to build a next system, particularly one that avoids a second-system effect. Oftentimes, the questions or problems are of the form "we have tool X, and it does job J, but we have this other job, J', and it's … sort of like J? Can tool X do it?" Now tool X has never encountered this particular problem — by definition it cannot be documented — and it might be we need to change tool X. Again, experience makes this take a lot less time. Even for a well designed system, it still requires someone new to it to dig in and figure out first how it ticks before they can even approach such a question. The reality is, of course, far less rosy, and there are many places where the docs could be better, often a lot better. But we've lost the most qualified person to improve them!