Soft Skills Engineering - Episode 252: Impossible documentation and unexcited coworkers

Episode Date: March 15, 2021

In this episode, Dave and Jamison answer these questions: Questions How do I incentivize people to maintain documentation? Getting anything done at this large enterprise company is a massive challenge because documentation is constantly out of date and people only have half the information needed. So much time gets wasted because people have contradicting knowledge about the status of projects, systems, or requirements. Should I just quit my job or can this be fixed? Greetings! First off, great show - thanks for the countless episodes, most of which result in me getting weird looks as I chuckle to myself while running and listening. I have a passion for technology which lead me to a career in development. I am very often researching new languages and software that will help us do our jobs and/or lives better in my free time. I get excited about these things I find and want to share them with my co-workers but often get rebuffed by them, asking me why I spend my free time “working”. I know I can’t expect everyone to share my enthusiasm and passion for this stuff, but I am finding it discouraging being on a team where this curiosity is not celebrated/encouraged. I love the company I work for and don’t want to leave, but I find myself becoming more and more disconnected from my team because of this. Any suggestions on how I can share my passion with my co-workers is a way that is mutually beneficial to me and them? Thanks, keep up the great work! Show notes Gary Bernhardt’s WAT video from 2012: https://www.destroyallsoftware.com/talks/wat

it takes more than doing sentiment analysis on video feeds during zoom calls to be a great engineer this is soft skills engineering episode 252 i'm your host dave smith i'm your host jameson dance soft skills engineering is a weekly advice podcast for software developers about non-technical stuff like how to use computers to interpret the emotions of your co-workers that you are unable to interpret you know what's good at emotions computers i like the idea of this uh very controlling boss that wants to turn people's frowns upside down so they use sentiment analysis to detect when people look grumpy and then put like a snapchat filter on them to make them have a goofy smile morale is way up oh look at how happy everybody looks so i just wanted to let

you know ceo that i have solved our morale problem productivity has plummeted but people look very happy so yes it's mostly solved you can't have it all yeah productivity is a lagging indicator yeah of course smiles happen first don't worry i wonder how long you could get away with that oh man like deep fakes just to just to make sure everyone thinks everyone else is happy eventually it will become infectious right people will truly turn happy if they only see pictures of themselves in the thumbnail as happy versions of themselves has anyone played with gtp3 gpt i can't remember what the acronym is that that giant language model and generating code i've seen some stuff that generated react components from text descriptions i'm just

thinking about oh it's based on the deepfake stuff it's sort of like deepfake or text kind of almost yeah create a zoom feed that makes my co-workers look happy model perfect i want to thank our patrons and so i will thank you to question mark jonathan king testing is documentation dot org adrian board dink roman denisov fizzbuzz influencer oladapo fadje karen spainson ragnar horrison nick hathaway travis anders dennis bogdanov braden kane steven armand lee john grant taras haruk chris hogan agile ventures charity nick cantar and philip john basile these are the the illustrious folk in their names in the bright lights. Yeah.

Audibly, I guess, instead of visually, who are supporting the show at the level where we shout them out every single month or actually every episode. Yeah. It's Friday. You can tell. Thank you. Good luck.

If you want to join this crew, if you want your name, shout it out. If you want to turn on our podcast and then plug it in to the – Remember those, those, there's always some trope about a high school movie where somebody takes over the PA system. Okay. Like says nonsense. I don't know. You could do that with this podcast, I guess.

Oh yeah. If you go to softskills.audio, click support us on Patreon, contribute at the level that gets you shouted out every week, then sneak into the principal's office, do some hijinks, plug your cassette tape into the, that this podcast is on into the PA system. oh man i feel like you would get expelled and i feel like that would not go so well these days hijinks are frowned upon a little bit more at school now yeah you'd probably be labeled a terrorist or something yeah i think you would but you won't if you do that because they'll recognize you're a person of taste and quality because you oh yeah soft skills engineering

they'll hear the pa start crackling and be like oh and then they'll hear that melodious soft skills engineering intro music and be like ah clever yes if you contribute to our patreon then your money helps fund the production of the show and you get invited to our slack team which is great yeah and sometimes you get more than one invitation sometimes you get an invitation every single month depending on whether that same slack bug has regressed again yeah do you hey do you wish you got more email well you can sometimes and it will only cost you a little money yeah what is it worth to get one email every six months or so that you don't want a hundred dollars a thousand dollars

what have i told you it could be yours for just one dollar oh my gosh that's all right an incredible value but we should answer some questions let's do what we're paid to do here we go i should read this first one i think this comes from a listener named will who says how do i incentivize people to maintain documentation getting anything done at this large enterprise company is a massive challenge because documentation is constantly out of date and people only have half the information needed so much time gets wasted because people have contradicting knowledge about the status of projects systems or requirements should i just quit my job or can this be fixed yeah you're at

the wrong giant enterprise but if you quit your job and go to the next one then they will have documentation figured out oh yeah you've solved it this this enterprise doesn't write stuff down but the other one will there's got to be someone out there who does this well right uh no that doesn't have to be that's true can't i just mumble about the law of large numbers and then yeah i don't know what that means but i think it means that if there are enough companies some of them are good at documentation yeah i think there is something about that where it's like statistically speaking if there's enough of one thing and there's a non-zero likelihood of having some property on that thing then you'll have the thing oh this is the infinite monkeys thing that's true given

infinite large enterprises one of them will by accident produce good documentation yeah that's always accurate yeah i work at a large enterprise it's a massive challenge because documentation is constantly out of date and people only have half the information needed so a lot of time gets spent by people trying to gather knowledge of status of project systems or requirements and yeah you've you've identified the thing that happens you're like joe is that you from the cubicle down the hall wait a yeah wait a minute my co-worker my co-workers there are only 50 000 of them again law of large numbers this listener is probably your co-worker yeah that's true i'm just gonna start saying if the irs gets mad at me for not paying enough taxes

I'm going to say a lot of large numbers given enough people you'll probably get it wrong sometime I guess and see if that holds up yeah what do you do about it so this doesn't feel good but lower your expectations is one thing you could do this doesn't sound abnormally bad maybe it's worse than normal and it's hard to get that across in a paragraph but it's hard to write documentation and most people don't because of that it's funny how most of the time those of you who have listened to more than i don't know two of our episodes know that there's a bit of a pattern to our answers which is find out who to talk to then figure out what to say to them but this one was an unusual one because jameson just said just lower your expectations and deal

with it they already found out who to talk to it was us and what they had to say to them was this question. And we solved the problem by telling them, yep, this is unsolvable. I've spent some time trying to think about why this is and why it's so hard to kickstart good documentation when it doesn't exist yet. And part of the problem I've encountered is that you run into the situation where to create documentation, you have to first document everything. If you add a new feature to an existing system, but the documentation for the existing system isn't there, do you document the whole system and then say and now it has this feature um and the answer is no because people don't do that or do you just like make some random entry somewhere that that says no one knows

what the system is but it says now it has blockchain that feels not very useful too so there's sort of like a hump to get over to get this started and that hump you're saying is documenting everything to start yes or at least enough it's what's that old carl sagan quote to bake a cake you must first create the universe create the universe yeah something like that yeah that's what it feels like sometimes another problem is there's never enough time to do it and this problem is sometimes caused by lack of documentation but you're going to have even less time if you take a bunch of time to document things in the short term it's really hard to see through that to the long-term payoff often lots of that long-term payoff goes to other people

too not to you yeah because you quit your job in frustration after trying to do the documentation yeah and then someone else joins and they're more productive because you wrote that down but but no one it's hard to say oh thank you person who left five years ago for writing yeah like we'll give you a retroactive raise odds are someone is doing this at another huge mega company and you're going to quit your mega huge company after putting in place this documentation foundation and you're going to go over there and be the beneficiary and they're going to come over here and be the beneficiary okay so it's like pay it forward yeah eventually it'll come back to you today you tomorrow me yes okay tomorrow both of us yeah i found that the tighter i can scope a a

request to document things the more likely it is to happen if we just have nothing and i kind of throw my hands up and say ah we have no documentation we should have it we still don't after i say that it turns out yeah but if i say we have meeting notes and we write them down and we put them in this place for every meeting and it rotates who does it and like it's very specific and it just happens and that starts things and now you have a way to derive current state documentation by reading the history of all meeting notes that have ever happened to know what the state of the system is now yeah it's like event sourcing that's right yeah yeah perfect and that's very easy for people to do to read all those and maintain state yeah well i was

gonna say it's better than nothing but it is potentially worse than nothing because if they read through a bunch of stuff that doesn't apply anymore then it could confuse them yeah you're like 80 of the way through this like 100 page meeting notes and you're like oh they threw everything out at this point and started over but at that point it's like literature it's not you're reading to find out what happened not to do your job yeah it's like anthropology about the system instead of the system yeah you want to see the character development yes the arc is what matters here yeah i had another thing to say that i felt very proud about and it's gone why don't you say a thing and i'll pretend like that's what i was gonna say

well i do i do have a semi-serious answer to this but really though before i give that answer i gotta say if you don't have top-down support to make this happen it's probably never going to happen for two reasons number one top-down support is required because people feel like they need permission to move slower to document things when they start and when they finish and number two they need to be encouraged to do this and know that it's part of what makes them a good employee is to produce documentation or else like we see in this question people's default state is just to build and not document yeah i agree with you that's what i was gonna say i have seen top-down documentation changes work i have seen bottom-up fail for a long time

which is depressing because what do you do if you're on the bottom and you want documentation you quit your job i think or you just give up because like it's very very hard to influence an organization to change this habit from the bottom yeah and that was going to be one of my questions to this question asker which is who are you in this organization are you someone who has formal influence or are you someone who is just kind of clamoring from the bottom you're a cog in the machine trying to get your neighboring cogs to write stuff down yeah because both of your suggestions are much easier if you have power because you influence what people get recognized for that sort of solves the problem of if you spend all your time more time writing stuff down

you're spending less time doing things and so if you're expected to just do things then you're less productive in people's eyes but if you can value and reward documentation as productivity then that incentivizes people the reality though is in my experience effective documentation culture which i have seen at scale at very large companies well one effective documentation culture comes by writing first not last it's not build a bunch of stuff and then go back and do the drudge work of writing down what you built it's writing down what you plan to build using that as a tool for reviewing with others to make sure you're building on the right track and then build it and then and this actually doesn't happen even at good culture good documentation culture places go back and

update the thing that you documented to make sure it matches what you actually built because there's always a small delta you know because the building process teaches you things but that where i mean that works really really well the other thing you can do is you can hire hundreds and hundreds of engineers not to write documentation but rather to bombard your team with questions about their software so that they realize i just got to write this down or i'm going to keep answering the same questions over and over you force them you sick an army on them yes that's a startup okay this is a startup idea it's documentation incentive as a service so you you pay my company and i will i will have engineers call your engineers on the phone and just start asking them questions about

their software and they'll notice repetitive patterns in the questions until they write and then they just start sending links back to the people and then you can cancel your subscription. That doesn't sound like a good business for you though. Yeah, the recurring revenue model, it's like we're successful when our revenue goes to zero. You just haven't achieved scale yet, surely. Yeah, yeah.

Surely if you just acquire more users, then it'll hit some inflection point. Yeah, where it goes to zero, so good. Yeah. you have so much stuff going to zero oh man yeah you'll have scaled really huge i mean maybe one thing you can do is make specific if you are agitating from below make specific assessments and suggestions because i suspect that your boss probably wishes documentation were better too but feels like they for whatever reason for whatever reason cannot make the trade

offs required to make that happen so if you just say oh our docs are bad then have a dirty secret which is that sometimes managers hear the same complaints over and over again and they stop caring about that complaint oh no yeah not me i care about all your complaints right you just don't do anything about them what are you talking about i host a successful podcast to solve everybody's problems that's right if anyone asks me a question at work i can't answer i refer them to our large backlog of episodes and then that'll distract them for a while it'll buy me some time there are there is well over 100 hours of material there that you know and that'll take weeks for them to get through yeah and maybe you know sometimes you

don't control how people interpret your words and and maybe they will find a solution that i didn't say which is probably your best bet yeah i had a point what was my point oh yeah if you can say a specific cost like i did this thing this task took me 15 hours i know that other person did this task a year ago if they had written it down then it would have taken me one hour or something something very specific and scoped and and specific and scoped to a task and and ideally some kind of estimate of here's how much time it would have saved because that can help buy you i don't know what to call it investment that can help buy you effort yeah resources it buys you willingness on the part of your manager to invest in the problem yeah i couldn't tell if you're

going serious or funny but that was good that was what i should have said i can't tell if you're going serious or funny is the tagline of our podcast keeps you on the edge of your seat and anytime you we give you bad advice that's because you misinterpreted it as serious yeah it was a meta joke it was just funny yeah it was post-ironic humor all right well i will say one last thing on this topic which is nothing speaks better than an example if all you do is say to your manager we need more documentation that doesn't really work very well but if you can show them how it works by doing what you think should be done that speaks a lot a lot better and your co-workers will really appreciate you and they might just pay it forward

as well and you could become a viral documentation infection that spreads with a really high r value but it's a good thing it's a good thing right yeah too am i too soon on that i think i am wait till i get the vaccine at least okay have we answered the question i think so good luck and you're i really do think you're gonna either have to just deal with this or leave because it is so hard to influence these mega huge corporations and change your culture culture from the bottom up yeah i've i've wanted to change it for years at my current employer and i've tried to agitate and i have some power and i've failed and finally i feel like there's enough people plus some top-down pressure that it's starting to change but i can't tell if i

did anything or like did i agitate for long enough or did it was it really just top down i don't know yeah i'm sure it was you yeah probably it was me now i'm certain uh i'm gonna read the next question this is from an anonymous listener greetings first off great show thanks for the countless episodes most of which result in me getting weird looks as i chuckle to myself while running and listening. I have a passion for technology, which led me to a career in development. I am very often researching new languages and software that will help us do our jobs and or lives better in my free time. I get excited about these things I find and want to share them with my co-workers, but often get rebuffed by them, asking me why I spend my free time, quote, working. I know I can't expect

everyone to share my enthusiasm and passion for this stuff, but I am finding it discouraging being on a team where this curiosity is not celebrated or encouraged i love the company i work for and don't want to leave but i find myself becoming more and more disconnected from my team because of this any suggestions on how i can share my passion with my co-workers in a way that is mutually beneficial to me and them thanks keep up the great work oh this is a very interesting mismatch of passion and what's the opposite of passion complacency doldrums disinterest dust i feel like we've answered the opposite question before of someone who works with someone else who who is very passionate and does a ton out of work outside of work and they feel like they can't keep

up this is kind of the flip side that's a good counterpoint because that might explain these developers not just lack of enthusiasm but active stifling you know like stop that maybe it is because you're making them feel that they're they don't measure up i have felt both sides of this and i'm trying to think the the i think i've been kind of a curmudgeon sometimes when i felt like it wasn't enthusiasm about learning new stuff it was like we must switch to every new thing that i read about on a blog post this week so when it affected my day-to-day by making me have to spend a lot of time debating or or just like throwing out work to cycle through frameworks or databases or programming paradigms or something yeah that's when i have been discouraging i guess or just in

disagreement so maybe they're perceiving it as like not check out this cool thing i learned but hey we should we should spend six months implementing cool thing i learned in production yes yeah and and your your complaint is that six months isn't enough you should spend more time on just curious no i just i just don't want to learn anything anymore okay i'm i'm done it's like after you eat one one pizza slice too many that's how your brain feels after 20 years yeah it's like i have all my work to do and now i have this fake work to it doesn't pay me it doesn't yeah it I mean, I guess it still pays me, but it doesn't check off my checklist fast enough. This is exaggerated for effect, but I wonder if there's some of that.

Yeah. I got to say one thing, though. I just don't want to send the wrong message here by not saying this, which is I love the fact that this listener is doing fun learning in their free time, learning new programming languages, studying things. I think it's absolutely fantastic, and I love that they want to share things with their coworkers. And I just have to say that if you find it hard working in a place that doesn't welcome that, I'm hiring.

So just send me a message on Twitter. I love hiring this kind of person. And I get it. Not everyone can afford to do this. But those that do, I really like working with these kind of people. This is revolutionary because we've gone from quit your job to get this job. Gone full circle. You still have to quit your job, though.

i'm not gonna pay to do both yeah i i agree that in general i like people who are interested in learning new things yeah and more than people who are the bad version of what i said who are full and don't want to learn new stuff yeah maybe you can find some of this outside of work there's meetups and online communities and stuff yeah remember when we used to go to meetups yeah that's true there aren't meetups there will be again though soon yeah that's yeah someday there will be meetups but for every cool technology there's a online community for it they all have discords or ircs or whatever so you can hop in there and learn stuff that's a good idea in fact i've known a lot of self-taught engineers who connected with an irc community are they still

doing irc i don't even know this is like 10 15 years ago and they would actually make really good friends too in the process so you know if you're interested in haskell or something there's a whole community of lonely haskellers who would just love it if you would talk to them maligning haskellers really i love you all but seriously there are communities of people who are just open arms ready to meet people who are passionate and interested in the same things they are yeah and often if they're new things the people in these communities are incredibly excited when someone new joins because they're trying to get off the ground and they they love they're trying to bring more people in so do you remember when elm was new yes i do and going going to elm

meetups just felt like a really special thing yeah it was like we are all doing something really unusual i gave a talk about elm and then i hung out with the community a little bit i never got super super deep into it but it it there were like deep relationships there and it was exciting to be a part of so in other words fill your bucket through another avenue maybe your co-workers aren't the ones to do it yeah that's an option another option is maybe if you can couch it in how this will make their life better this is sort of to address the the curmudgeonly like oh you're just going to add more work to my plate yeah probably most of the stuff you're learning about is not going to directly apply and make their life better but if some of it does then

that's that's a way to get them interested okay this could help with this task that we have ahead of us so i'm hearing you say apply the law of large numbers and just spam them with everything you're learning and probably one thing will make their life better yeah yeah law of large numbers it comes up again applies it everywhere and in fact if you apply the law of large numbers enough you will eventually you'll apply it correctly once well that went really meta i like that yeah finding discouraged being on a team yeah that's that's rough when it's your team yeah so my organization has an off-topic channel where

people will post kind of random ideas and it's often cross-team the collaboration in there because it's not not necessarily everyone on your team is going to care deeply about some cool new thing you're looking at so maybe maybe there's this is sort of in between the find an external community and do nothing but you know find like a bigger internal community surely there's someone that you work with or that works at your company that is pumped about learning new stuff and being enthusiastic and passionate and maybe maybe you could find a low pressure way to share your enthusiasm that's not hey let's let's put this into our production code but instead it's just like a fun like maybe a lunchtime get together where yeah like brown bags are a thing well they

were when we went to offices and maybe make it kind of light like hey i'm just showing you some cool kooky stuff i'm not saying we have to make it explicit that you're not telling people they have to change the way they work just because you're excited about this and then maybe play a video every once in a while and i just have to say a really good unifying video for this kind of like quirky light in the mood but stay on the technical topic is of course the watt video everyone loves the watt video that is a classic you gotta throw a link to it in the show yeah we should just so like throw the video in there from gary bernhardt throw in some interesting kooky thing you've learned about or just you know show how you can like launch an entire who knows

xyz stack in three lines of code in in five seconds so set that up make it lightweight and fun and maybe try to get your enthusiasm to be infectious here we go again with another infection metaphor but try to get your enthusiasm to be infectious in a low pressure way so your team doesn't feel like you're asking them to change the way they work yeah one thing i really like My current job is we have a bi-weekly, we call it the learning extravaganza because I titled it and sometimes I give stuff goofy names. And that's what it is. It's come and teach us about something. And probably two-thirds of the time it's tech.

Sometimes it's about home maintenance or how to cook Israeli food or just like other random stuff people are interested in. But it's a form for people who just want to learn and people who want to share what they have learned. it's low pressure it's like valuable for team building and learning new stuff and people find it enjoyable and the people that don't care they just don't show up and that's fine and what what percentage of the people who are invited show up every time would you say oh so we're pretty distributed across time zones our whole org has i'd say it's about half the org that shows up okay that sounds great yeah at my previous company we did lightning talks every i don't know two months or so for a building of about i don't know 500 to a thousand people and we would get like

eight or nine lightning talks every few months and they would be really interesting esoterics everything from like brewing beer to building a koi pond in your backyard you know it's pretty interesting stuff to brewing beer in the koi pond in your backyard it's like raising what's that what's that special kind of cow that's raised on beer and massaged before it gets eaten what is Is it Kobe beef? Is that a real thing? Isn't Kobe beef, it's fed beer and massaged and then slaughtered and put on your plate?

I know it's expensive. I'm saying you could do that with fish. Yeah. That you brewed in the pond they live in. You're going to get some nice extra complex flavors in that drink, I would suspect, if you brew it in a fish pond. Yep.

Is that a hint of slime I detect? All right. I've answered the question. I think so. Yeah, we're good. My wisdom is used up. We're good. Let's wrap it. Squeezed all the wisdom juice out of my brain. What should people do if they want more questions answered? If you would like more questions answered with comedy or seriousness that is unpredictable, go to softskills.audio and click ask a question. And we just want to say thank you to everyone who has submitted a question. We will eventually answer all of them. We promise. And that is a check that we might not be able to cash, but we're going to try our best but we promise promise to that's the promise sandwich you promise and then you

caveat and then you follow up that caveat with a promise perfect i think we're done catch you next week I'll see you next time.