How To Write Like It's Your Job

please welcome Bree from Bishop Fox all right hello security riders we're here today to consider some aspects of writing and editing that wherever you are in your career you may not have focused on before let's check out a map of our general trajectory underpants you the first draft space using guides and fresh eyes to edit yourself and what to do if you need more so our first stop underpants in an episode of South Park tiny gnomes sneak into kids rooms to steal Underpants why would they do that they explain it's step one of their business plan which is missing a crucial middle part between collection and profit my conceit here is that you right now basically hack all the things in

step one and you want payment and closure for that in Step three but if you don't use step two to consider the quality of your work if you turn in your first draft as your final draft people will be less inclined to pay you and let you move on they'll want to go back to step one and scrutinize what you did and make sure it's worth paying for but if you have a real plan you make your work with care you look brilliant in step three you keep everything moving and most importantly you get paid for your time and can work on the next thing for more about what happens when you miss the middle step you can look at my

cactus con talk from a few years ago called chaos on the machine it's a jolly twenty minutes about the value of making security writing more transparent for this talk let's just agree that you should avoid writing breaches with a double e and we'll focus on the solutions so what's our new plan it's a five-step plan our goal is to make something good to produce quality content that reflects the quality research business experience and expertise that you put into it so first we're going to focus on you and how you make things then we got to make a thing then we need to focus on how to make things good how to set up ourselves for

success so that in the fourth step we can execute on that plan on the things we've learned and do them resulting in a beautiful thing that does what you want it to my hope is by recognizing these steps every time you walk through them you'll be able to see the profit at the end of the tunnel so the first step of our new plan is knowing how you make things as a writer and the first step of that is admitting you're a writer you might categorize yourself as a bad one but it still makes you a writer acknowledge that it's an aspect of your job in emails meeting notes CFPs cover letters and bugs reports you write admit that embrace

that before we can achieve a gleaming palace of paragraphs though we need on how you write what is your process right now if you don't have an intentional process there's still a pattern you can notice about the time of day or place or format you choose to write in what keeps you motivated and what stops you from trying anymore it may be ad hoc but it's kept you employable so let's find the outline of your current underpants known plan before we flesh it out if you've never checked in with yourself about writing start to notice your patterns and emotions about them just get to know what you're working with are you great at starting terrible at finishing big

procrastinator but you always pull it out at the end somehow maybe there's someone you go to to bounce rough ideas off of or someone you know to only show the final version to you may even find you're carrying around grammar pedantry from a teacher that's not doing you any good take inventory of your writing assets they may seem small but they add up to a universe of productivity look at a recent email blog post or report you've written and consider what areas you're confident in and which ones you avoid or struggle with what's working for you right now today how do you communicate on paper over time you may start to see that you fall into the

extreme edges of the ranges here you might write to casually for reports or to seriously in emails you could be so brief that the reader doesn't feel they've gotten their money's worth or you could write so much that they feel like they've walked five miles and ended up in the same place these are independently moving ranges all combinations are possible basically you want to be somewhere in the middle on all of them if thinking about your current writing style this way is tricky you can make a list of things you enjoy or struggle with in writing instead for example I enjoy giving talks because I naturally write in a conversational manner but I need outside accountability

to keep me honest and my talks always go over by a minute as you figure out your strengths the strategies that might work for you will become more obvious like if you feel lost when you sit down to write you may need to take detailed notes as you're doing the testing so you don't have to remember the facts on demand or you may need to let the experience simmer before writing so you shouldn't beat yourself up for not sitting down immediately after the event before I move on I want to briefly address writers who learn English as a second or third language as I hope you can see from this talk already writing is legitimately difficult for everyone

so tackling it in a second language takes real focus and work make small goals so you can celebrate small victories of progress and look back on old writing to see how you've matured give yourself even more time for your writing process ask for peer feedback and take notes on what you learn from each document I also recommend that you get more formal English in your head little things like prepositions irregular verbs and idioms are hard to just memorize but if you listen to things like grammar girl structured podcasts about security old DEFCON talks or anything else you're interested in those little building blocks will come to you more easily when you sit down to write all right we're all writers before

we can make a good thing we need to make a thing let's write the first draft how do you start writing though blank pages are terrifying here's how you write a draft you write it jump in do work where you can do work right now maybe you can knock out an outline or the main point of the report in casual language like hey company don't use that third party vendor or your scope was a joke do this test again with a realistic set of targets in draft two you can make those phrases more diplomatic but don't censor yourself in draft one get the core guts of your message out on the page on that note the biggest hurdle

I see stopping technical writers is dressing up their language before they've put on their underpants be comfy in your first draft the stiff formal wear of these phrases can restrict your ability to move around and early drafts by focusing too much on the way you think you should be writing don't worry about misspellings don't look for better synonyms just use a verb you can readily think of and leave a note for later none of the things on this slide are inherently good or bad but you might be over relying on them to sound confident just consider that they're repeated use and misuse and they actually be weakening your points don't use bits you're not sure how to use just write

down what happened as well as you can and save the formal wear for the editing process for the things you don't want to do or can't immediately dive into in the first draft mark them as spots to fill out or improve later I recommend using comments rather than highlighting or bolding for this because those tools eventually lose their power to stand out and can sneak through to final versions ok so you've written the first draft now what well to make things good you have to make room to make them like many many business failures errors often get through because catching errors wasn't a defined part of the process if it's no-one's specific responsibility it's not surprising that

it doesn't happen you have to make it a deliberate step the biggest point of this talk is that if you want to improve your work which is what editing is you've got to make space for it such a downer I know and it's good to admit that you might hold a grudge about editing it's not the reason you get up in the morning it's a barrier between you and the next fun thing and honestly people can be cruel in their blood feedback you may have had a teacher dismiss you as a writer or a colleague give you a vague comment like this is bad fix-it reviewing an edited text from unscaled editors can be demoralizing and

yet editing is such a crucial part of refining your craft and succeeding at your job rebound from those literary traumas by learning to find the useful feedback below and be grateful when you get to work with professional editors so let's make some space for editing we're gonna focus on three ways here first you need to know how much time you have total so you can carve in time to edit this can seem simple but little admin tasks can cut off fractions of days and really affect how well you can finalize your work before the deadline get that information up top and clarify when necessary you need it you need to know the real schedule so you can plan your

attack and wrap it all up at the end - you can make space by creating your own schedule within the official timeline set up chicken meetings with your project partners talking through your topic can often clarify your message and shake out forgotten points keep the meeting short and then you can use that blocked off time to make headway on the next section or review your work with fresh eyes while you'll feel that momentum and build out generous amounts of time in your schedule for your colleagues to review your work peer editing can be rough so keep it focused by asking for feedback on specific areas you're working on your introductions transitions or technical explanations 3

save time during editing by spending time now to get to know your tools better all word processors have little tricks that you may not be taking advantage of set it up so it's your friend not your enemy during deadlines if you're using something daily it's worth looking up tutorials to get comfortable with the various ways to view and format your work for example how to customize your spell check settings how to bring the common functions you use onto the quick access toolbar shown here how to use track changes and its different markup views how to talk in comment threads how to accept changes okay so we have allotted time for editing and you've written the first draft it may

not be pretty or concise or completely filled out but it has the beating heart of the message you're trying to get across now we can talk about making it good first drafts do not make good final drafts because they're really you telling the story to you you can use shorthand you can assume that the timeline main sense and just focus on the parts that interest you because you're the one who experienced the exploit it's like if you write a shopping list that just says milk but then someone else has to go buy it what percent what size did you mean almond milk these are the kinds of clarifications that a technical editor would ask you about and that you have to

take a step back and ask yourself if you're going to edit your own work and to do that you need to be different from who you were when you wrote it so the first thing is let's use some of that space we allocated earlier to let our draft rest so we can really improve it the amount of time here is not crucial you just want to give yourself a chance to separate yourself and live a little so that when you come back you can experience the document like a new thing if you edit right after writing you'll miss boodles of errors because you haven't distanced yourself enough and at the same time you'll burn yourself out

sleeping on it really does help but going for a walk playing a game singing or dancing can make you feel like you have something new to offer when you come back if you're short on time consume the document in a new way by listening to it out loud or changing the format you're viewing reading out loud or having a computer speak it back to you is the absolute best way to edit yourself why when you silently read something back to yourself that you've just written you fill in gaps and you miss words this triangle is a classic example of that I love Paris in the springtime oh dang there are two those in that triangle but because of

the line break your brain kind of half remembers that little word and lets it slide during a quick scan but it sticks out when you read aloud you're so embedded in your topic that you won't see or hear these little connecting parts that you just assume are right beyond typos there are a lot of eccentric there's a lot of eccentric jargon in security that you may not hear is strange anymore when those terms like sniffs run pickling pop up out of context that can confuse new readers or be unexpectedly suggestive the words that make them up don't have to be inherently vulgar but in InfoSec terms I recommend watching out for our penetration dump leak Jack and dangal four of which were

combined in an end gadget headline last summer according to a hot dongle leak so a slogan for editors is read stupid think dirty if there's a confusing or vulgar interpretation of a sentence people will find it and then they'll talk to you about that instead of what you intended for them to focus on these phrases make you memorable as a writer but it's probably not the kind of attention you wanted so read your work out loud to hear what it really sounds like by letting it breathe and reading it out loud you get to experience this document like you're totally new to it and when you hear it for that first time capture your reactions if something

seems off like this map it's probably off you don't need to know the solution to the problem right away but you do need to mark it before you get too comfortable on the document again and forget some questions to ask yourself is the sentence so long I run out of breath do new topics appear out of nowhere our terms used inconsistently are their repetitive phrases about attackers attacking and users using right those initial reactions down even if it's just a keyboard smash comment in the relevant place that's what I do on my first pass you can run spellcheck to mark potential problem areas - and while we're on the subject let's look at what guides and

tools can and can't do for you in the writing process there are so many gray areas and nuances to language that unfortunately no one tool can fully replace a human editor so I recommend you use a combination of reference works existing tools and your own custom checklists during your editing and finalizing phases the benefit of an existing tool is it already exists the possible negatives are that they don't work with your specific vocabulary or custom formatting and in the case of a tool like grammarly they check your writing remotely so if you're dealing with client sensitive NDA type information it's not the tool for you if you are in the market for some readily available guidance though I'm going to

suggest to that I helped create the cybersecurity style guide is a friendly PDF with 2,000 terms how to write and pronounce them what they mean in different contexts which ones to consider avoiding this is a page of entries from bootloader to be sides and appendix at the back has further resources for technical writers books I recommend and other modern style guides that can support your work the second tool here is cyber dick which is a dictionary file that augments your word processor spellcheck by adding those 2000 terms from the style guide directly into your local dictionary that can keep away those distracting red squiggly lines while you're working on your drafts these are both available now for

free I made them to make my own life better and I'm happy to make the writing price process less painful for you going forward the reason I recommend using a combination of reference works tools and custom checklists to navigate is because there really are no rules only guidelines I really mean that English is a wild and greedy language and there aren't many hard rules it's good to reference industry standards but you shouldn't feel trapped by them if they're outdated or don't apply to your situation sometimes in writing it feels like you're searching for that one perfect word or phrase but the reality is there are a thousand ways to write a sentence that could serve your purpose many

answers are right it just depends on your goal your audience and your timeframe it's an editor's job to keep the final audience in mind all the time the changes they suggest are not really about an editor's personal peeves or preferred sentence structure it's about fighting for the user like Tron you want your future reader to get your message to do that you need to keep them engaged focused and on track sometimes this means cutting out parts you loved but aren't relevant or rearranging your structure to explain the basics up top before diving deep a lot of this comes down to keeping a specific audience in mind is this for CISOs developers Instagram influencers or your elderly

family members even if you hope everyone will read it you should be a realistic about what level of reader you're aiming for it affects everything from word count to format to how many of those fancy trap words you feel obliged to put in the final draft the best way to note to fight for your user and keep them on track is to give them context so they know what you're going to tell them in what order and why it's important a comment overall strategy here is to use parallel structures if you were making three points you should use a single system point one point B and lastly including sections like a tldr or walkthrough up

top are also good ways to clarify time and place don't suddenly teleport your reader without warning laying out these roadmaps is about setting expectations and then meeting them if you don't provide a road map you might lose your reader in what are called garden path sentences you the writer know what they should say but the twists and garden path sentences mislead until the end which can make your reader do a double-take let's look at two the team found oh the team found something a vowel and end point oh they found a sample application where was it hidden why does it matter ooh this sentence is not about finding an application this is about finding something within the application so

we'll add a little word up top to make that more clear early on the team found that the sample application had a problem in this example the name of the team application and problem are short but this type of sentence structure appears all the time and technical writing with complicated noun phrases in each slot and your readers will get lost if you don't keep them in mind and hold their hand through long sentences if you find yourself needing to give extra context in the middle of an important sentence I recommend putting it in parenthesis or its own sentence or in the footnotes separating secondary facts in parentheses or note sections keeps your main message clear and keeps your

reader on the path all right example 2 the overall security of the external network was excellent sometimes the sentence itself is clear but it's true meaning isn't known until something later if I read this as a client I'm happy I'm mentally resolving this report in my head and moving on with my day next sentence the team extracted 60,000 social security numbers from the internal network dang you just sucker-punched your reader it's not kind like now they feel betrayed you sweeten them up with a compliment and the rest of the organization is on fire let's rephrase this although the external network was well secured the team extracted so much from the internal network now we anticipate

the bad news we're not whipping the readers expectations around it's the same core information but you've given it context you've prepared the reader and you look like a professional you haven't ruined someone's day now you've just laid out the strengths and weaknesses to a CSO so they can act on this information this level of paying attention to sentences that sound could be daunting but in general editing technical documents comes down to simplifying your structure so that the only thing that reader is having to spend brainpower on is the concepts in your sentence not the sentences themselves break up sentences use strong verbs pull long lists out into bullet points and use transition words to keep

your reader flowing smoothly through your document as you're wrapping up your close reading of a document go back and read the beginnings of everything not just the intro paragraph but the first sentences of every paragraph and the headings for each section reading those bits back to back separate you from your role as writer again and let you see what the reader is likely to take away from your piece in the end lastly go through a finalizing process you've decided on ahead of time that uses that combination of spellcheck pre-made tools and custom checklists if you can look at your work in a PDF and scan it for visual consistency make sure all the figures look like right proofread the

cover page the dates the heading titles the table of contents and the figure numbers to make sure that parallel structure and consistency is happening headlines are a common blind spot that's how you get hot dongle leaks and it's good to check that your legally covered make sure that your redacted content is really redacted and not just covered with a black bar those can be removed from PDFs and remove metadata so clients don't know you name the image idiot client JPEG you can't edit forever and there's always something else to consider improving in a document but at some point you have to stop there are a million tips and tricks and editing but I don't want you to be overwhelmed here

this talk is to help you view the width of when an editor considers so that you know in the future that there are strategies and resources to turn to it's not just you struggling to write it's everybody and even editors argue about what matters most so with you as my reader as my intended audience in a movie theater let's take a step back and look at the big points of editing before we wrap up the whole talk for editing read your work out loud capture initial reactions read stupid think dirty use a combination of guidance remember your audience keep your actions clear by keeping your sentences short read the beginning at the end and finish strong with a

checklist so you don't undermine all the good work you just did what if you need more than your editorial abilities can offer there are amazing freelance technical editors in the world that can help you hire them if you do that or if you already have access to an editor through your work you should give your work to them in the best possible condition and include notes about what's missing and the aspects of writing you're working on editors are powerful but they are not ammunition omniscient so the new plan to fully dress up our documents in more than just underpants one learn how you make things by knowing yourself as a writer to make a thing in this case a

bad rough draft three make space for editing and prep your tools so that in four you can edit and finalize that doc and profit from your hard work I thank you for your patience through this obstacle course of writing writing is ridiculously hard it's hard for me just know that there are resources and strategies you can implement today to make this aspect of your job less painful and there are things you can quantify about yourself that you can use to decide which of those will be most likely to help you you're all writers and I wish you the best as you continue on your lifetime of writing editing is hard and I empower you to improve your

own documents thank you for your time and here are the details where you can find me in these slides in the future if anyone has any questions I can answer them or I'll stick around in the hallway afterwards oh so many phones I can't see anyone so if you'd like to shout you can well we can all just have a nice time in oh thanks I brought an entourage thanks coworkers yeah okay well thank you everybody I'll be in the hallway afterwards [Applause]