HELP! My Technical Writing SUCKS As A Software Developer

Transcript is auto-generated and may contain errors.

all right I am leaving CrossFit it's early it's 700 a.m. Monday December 23rd I got another thing from Reddit we're going to go through about clear writing let me get these windows cleared off there's a huge truck behind me it's kind of sitting in the middle of the road um it's going to be interesting everything is foggy no one's coming we're good we're good we're good okay um so this one from Reddit is interesting I do like it um it's regarding writing and writing clearly so the uh the op is basically saying and this is really common actually like English isn't their first language and um they're kind of getting to a point in their career where they're noticing some of their soft skills like clear technical writing just kind of catching up where they're like oh crap this is pretty important um and they're

getting some feedback from their manager um that they I don't know like need to improve on it which you know it's good feedback to have and so they're trying to figure out like okay good chunk of the way into my career and really need to start focusing on this like what should I do right so again this is just just a really I think it's a solid reminder to folks like your communication skills are incredibly important I think they're uh they're very undervalued especially for more for more Junior people getting into software engineering because they's such a focus on technical skills um and then to the point where we like essentially start neglecting the the softer skills so um please as I put it pardon me my my lungs are not keeping up with the the workout but uh as I put out content and

stuff when you hear me talking about soft skills please don't get annoyed by it it's just like I need to constantly put out this reminder to folks like just how important it is um so um before I dive into it just a reminder if you want questions answered write them in the comments if you want it to be anonymous or you want to write more detail and you don't want it in the comments look for Dev leader on social media uh write me whatever you'd like within reason of course and um if I can help I'll try my best to make a video out of it and I will do another shout out because I have a live stream on my main Channel Dev leader so if you feel like this kind of content and you're not necessarily looking for um a more polished video

like my main channel has really polished videos I pay an editor he does my thumbnails and stuff um there's a lot more tutorials and things like that if you if you're if you're not interested in that but you still like this type of conversation um the live streams that I do Mondays at 700 p.m. Pacific on dev leader are on topics like this but there's a live chat right it's actually live so um I try to make sure that I'm engaging with the audience if you have questions that aren't even related to the topic it is supposed to be more like an AMA but I always prepare a topic that topic is always my recent newsletter article so weekly.

deev leader.com if you want to see what that's going to be about so uh please join me on Mondays for that it's uh I think it's a lot of fun I love answering questions and having conversation in the chat it's pretty fun so let's dive into it so um on technical writing and soft skills in general um this might maybe it's not obvious to some people maybe it's super obvious when I say it out loud but soft skills are just like any other skill right we have to practice them to get better at them and um like for some people some of these things do come more naturally so for example you might know you maybe you've met people in your life and they're very artistic naturally right like they just seem like they can draw very easily or some people uh they just have

some skills that they seem to pick up very easily they're just they seem to be good at it naturally that's entirely possible with many skills right but that's not that's not the common thing and essentially if you believe in growth mindset and I do um basically all all skills can be learned doesn't mean that given the same amount of time and effort as someone else that you'll be at the same level that's not what I'm suggesting but I do think that if you want to improve in an area like your soft skills for example or in this case more specifically for technical writing um I think you have to practice it and I think that you can make tremendous improvements by practicing this kind of stuff especially if you're going from like hey I never do Tech technical writing and like I'm getting some feedback

that it could be improved like if you're never doing it going from like never to at least sometimes I feel like you'll make a lot of improvements and um I think a key part here too is like having awareness right so for example if you never did technical writing you're probably not going to be good at it but because you never do it you also don't know what aspects of technical writing you're not great at because you can probably break down skills into different subcategories different things to focus on right even to give you an example just coming from the gym right coming from Crossfit um today we were bench pressing bench pressing is a a rare thing that we do in CrossFit uh but because my uh my background is like all bodybuilding and powerlifting there's a lot of bench pressing so I've spent

many many many years bench pressing right but compared to some of the other movements we do in CrossFit like cleans jerks uh like basically most Olympic lifts where there's some type of overhead movement um those are things that I've never practiced right I I have an idea what they are but I've never practiced them until CrossFit so if we take something like uh a a power clean or a snatch or a jerk like those skills for me are are horrendous compared to bench pressing but I've spent so many years bench pressing and so little time doing those other movements so now the amount of time that I put in when I'm at CrossFit to practice those movements oh buddy this is not a not a good opportunity to move over um you know the amount of time that I put into practice a clean or

a snatch or a jerk I will be making significantly greater improvements given the time put in for those things compared to bench pressing because I've already spent a long time bench pressing so my point is that um yes you have to practice but I I do think that when it's something that you haven't done a lot of you'll make um you'll make significant improvements which is great uh so having some awareness what to improve on and then putting in the time is going to help so when this person was described ring their technical writing and then some of the comments I did a brief scan um I think one of the most important things in communication is thinking about your audience so if you're writing a technical document and it's for other technical stakeholders you need to understand like what level of understanding they have

right they might be technical which is great you can talk about technical things but if you're you're using technical jargon that's specific to this domain that you're talking about and they don't have experience in it it's going to really reduce the effectiveness of your communication okay so it's one thing for the audience to be technical like you but it's another thing for them to understand all the technical jargon and more often than not I would just suggest that you steer away from technical jargon as much as possible so things like acronyms um if you can avoid them I think it really helps uh you'll if you might have found yourself in this situation where you're you're in a conversation or you're reading a technical document and it's just filled with acronyms and you're like I don't know anything about what we're talking about here and

that's just because it's technical jargon that you haven't been exposed to uh I work at Microsoft and I would say like one of the biggest challenges that I have found getting comfortable in different spaces at Microsoft is there are so many acronyms that uh it it feels very difficult I like to think that my soft skills in communication are are pretty decent given that I'm an engineering manager and I've been doing this for a while something I have to practice regularly um but even for myself it's very much like you know having to deal with technical jargon and stuff it's like it's it's not going to really matter how good my soft skills are when I just don't know what the Acron are so I would highly recommend when you're doing technical writing try to avoid acronyms as much as possible um you know if

it's something you're going to be repeating a lot and it's like you know multiple words that are constantly going to be repeated uh definitely try to make it clear rate at the beginning that there's an acronym so write it out show the short form of it um but definitely if you're talking about like other systems that you're interfacing with like please just stay away from the acronyms um technical jargon just really makes it difficult for people to understand um that could also mean um you might have names for different systems and maybe it's not even an acronym right but maybe you've given a name to something if that name is not easily understood to people outside the domain again like consider saying like we have a system we call it our system's called Dorothy okay Dorothy is not even an Acron what the heck is

Dorothy well Dorothy is blah blah blah I just I don't know why Dorothy even came to my mind I don't even know of a system called Dorothy but my point is that you might understand the things but you're not writing the technical document for you right we have to be thinking about who the audience is always this is the case for all communication not just technical writing the same thing happens in meetings or different conversations um you need to pick terminology language phrase things in ways that people are going to understand introduce topics in ways that make sense for people to start getting the flow of understanding um but this is especially you know uh apparent in technical writing right you need to introduce topics to people make sure they understand what's about to be discussed and get into it um something else so I

was scanning the comments I thought this was good advice and it's um I think good to practice and it means it's a little bit more work sometimes but I think it's uh truly worth the the effort that goes into it um but it's it's like starting by being being verbose in your writing and what I mean is like so say you're you you've identified for yourself you find it a little bit challenging to kind of scope down how much you're talking about um you write a lot right cuz you're trying to put in so many details but maybe those details like aren't in reality like you're kind of acknowledging this maybe your audience doesn't need every single one of those details or it's just it's too much right you're kind of zooming in too far on the specifics um you could do a first pass

like that and then try to go through and edit your document and start refining things start removing details that are too technical you can move them to an appendix if you think it's important information but it's almost distracting the level of Det detail so that's something that you could do but the um the comment I can't remember the exact words cuz I don't have it pulled up but the comment that someone made on this post was like uh and maybe it was even the original poster I can't recall but this idea that like if it's going to take someone 10 minutes to read something but you could have written it in a way that would take them five like do that like that's what people are going to want they don't want to spend a ton of time trying to digest and understand what you

have to say yes it's technical but we want to make sure that we can write it in a simple way with the right amount of detail and no like it's not it's not something you're going to get perfect the first time don't expect to that's okay it's like writing code right you'll if you're working on a team or a project for the first time you put up your first PLL request odds are the team who's been working in that code base for a while they're going to have some feedback for you right it doesn't mean that like you're you're stupid or you don't know what you're doing it's just like these are just opportunities for improvement so um you know I would say like don't beat yourself up over this kind of stuff like getting feedback is good um it might feel difficult it might

feel like oh I'm never making progress on this stuff it's but like you are right getting feedback is important I think having awareness that there's room to improve that's important right all of these things when we're getting feedback I think are very valuable and I know that um you know if the feedback starts to feel like it's one-sided like hey I'm only getting feedback about how to make things better I understand that can start to feel like if no one's saying anything good and it's only stuff to improve therefore I must be doing a bad job but that's not really true we can't necessarily conclude that so like don't try not to invent that in your head right people are giving you feedback because they want you to improve and they think that you're going to do something with that feedback I think that's another

good reminder right people don't give you feedback if they're like oh well Jimmy's never going to listen to that Jimmy doesn't care about anything right why would I give Jimmy feedback if he's just going to ignore it so people aren't going to waste their time giving you feedback if they don't think you're going to do anything with it they want you to do better they're on your side right that's why they're giving you the feedback so try to think about it like a positive thing which I understand is is difficult like I I realize what I'm saying is significantly easier said than done but try to keep that in mind um another thing that I thought and this might not be applicable to everyone listening and watching but uh hopefully at least some of the audience right um someone had said in the comments like

hey man like you should give yourself some credit for trying to do this stuff in a language that's not your first language like like seriously kudos to you and uh I I thought that was a great call out um I find it amazing right like I only speak English um and sometimes I feel like I'm not even speaking English that well right it's uh it happens um but for I always find it so amazing that people are you know we're working with them they're speaking English they're writing code in English and like it's not even their first language uh it's it's incredible right it's incredible so I think when people are navigating this space and truly English is not their first language like you know try to give yourself some kindness that like you're doing you are doing something remarkable um I'm obviously I'm fortunate

that I speak English and that happens to work well for for my career um and for folks that that's not their first language like I I mean it sincerely like I I don't know if I could do it so like I find it extremely impressive uh I know that when I've worked with employees uh from different countries and stuff in 101s I will often get feedback that people have um concerns about like how they're how they're speaking or how they're communicating like I know it's for many people where English is not their first language like they're like very um aware like they have a lot of focus on it like they want to do a good job and uh you know they they're they're critical of themselves and part of me is like I think it's good that they want to improve and do better

and like this is something that they're paying attention to like I mean awesome like I think that's great I think I don't think there's anything wrong with people trying to focus on areas and trying to get better but um but this is something that's like that's that's complex right to have to find an entirely different language to communicate in um so honestly like if you're if you're someone listening or watching right if you're if English is not your first language or you're navigating how to communicate effectively in a completely different language I you know like kudos to you seriously it's uh it's really remarkable so um do give yourself some kindness right um don't beat yourself up over it I like I said if I had to pick any language even if I could pick it like I learned a bit of French in elementary

school if I had to go write a clear design document in French oh my goodness not going to happen um but like if I had to for work like I would need to acknowledge the first one is going to be terrible and it's going to take me some time to do it effectively but there's some meta points here right aside from just the language itself um I think how we approach technical writing and clear communication there's some general guidelines which I tried to touch on so um one is really consider the audience their level of understanding two uh try to avoid technical jargon as much as possible it just it doesn't really add anything you're trying to make things concise generally I think but like by shortening the words until they lose their meaning it's not really that beneficial um it starts to be a

trade-off in the other direction and then the third one was around conciseness right like if you can find ways to uh not completely take some text and blow it up just like it's not like in a I think for some of us that went to college or university or even in high school and stuff it's like you need to have a an X number of word essay and it's like okay how can I take the sentence and make it more words we're not doing that here it's the complete opposite people don't want to waste time and you shouldn't want to waste their time right so uh if you need to write more of verose things and then edit it down I think that's a great exercise again details you don't necessarily have to cut them out you can move them to an appendix so that

means if you have a bunch of data points you want to go over and you're like I think it's valuable but maybe not you know the the focal point of this paragraph or something you could say like here's a point and like follow up in the appendix for other data points or something right um so I think there's lots of opportunities that way the the final part that I was mentioning was really around like you know having awareness taking feedback um these are these are things that we like any skill we have to practice them and having a feedback mechanism is very valuable to start guiding you where to put your attention right remember people want you to succeed that's why they're giving you the feedback people don't give you feedback to hurt your feel ings maybe maybe some do uh but if you're working

in a place like that maybe you want to reconsider that um but generally people are giving you feedback because they they are trying to help you and they want you to win so um if you can try to reframe feedback in a positive light I think it helps you try to to take advantage of it and leverage it so do make sure that you're practicing this is just like any other skill that might mean you uh try to take on more technical writing uh that might mean that you try summarizing things right uh you might go out of your way to write a summary for um work that you've done write a summary if you if you have like live site issues that you were investigating just finding opportunities to practice it uh with different audiences I think can make a huge Improvement because you

are practicing right it's going to be hard to improve if you're not doing more of it so I hope you found that helpful um like I said at the beginning of this if you have questions and stuff you want answered write them in the comments uh or find Dev leader on social media send me a message and I will remind you again on my main Channel Dev leader I do a live stream at 7M Pacific every Monday so tune into to that I would love to see you there answer questions live the topic is almost always the newsletter article no you don't have to subscribe to a newsletter if you don't want to read it like doesn't it doesn't help me if you subscribe and you don't read it right so I'd rather if you just want to check out the topic you can go to weekly.

deev leader. ca I put it out on Saturdays that means you have all Saturday all Sunday and all Monday to check it out before the live stream so hope to see you on Monday I'm recording this on a Monday but I probably won't put it out until tomorrow so I'll see you next time take care