Read the Fantastic Manual: Writing Security Docs People Will Actually Read

thank you for joining us today uh sorry today uh we're going to talk about uh read the sorry let me start this over again thank you for coming uh today's talk is read the fantastic manual a writing security docs people will actually read our speaker is brienne bowlin brianne bolin is a product security engineer with the security partnerships team at gusto before moving into security she was a site reliability engineer and an infrastructure engineer who did work in healthcare and gov tech and uh if there's any questions please post them on slido with hashtag besides sf2022 if there's time thanks well thank you very much uh hello b-sides i have not spoken in front of actual people in somewhere

between 28 months and 84 years and a very old lady on the titanic.give kind of way uh it's really good to see all of you this is uh thrilling in all of the connotations of that uh hi i'm brianne hello i'll tell you a little bit about me um as mentioned i spent some time in sre land and infrastructure before that for a bunch of years i was a professional editor which is why i have many opinions about many things you're about to learn about and you're also going to see my ux background poke out here and there it informs a lot of this stuff i'm also doing a signing of a book i contributed to called reinventing cyber

security at 3 pm up at the b-sides table in the participant room with my excellent colleague carla so we have free books they're amazing books i hope you come see us and in the vein of meeting lots of different kinds of learning styles where they are there is a blog post version of this talk at briennebolin.com if you like reading along and i also linked it on twitter and if you're a person who posts stuff and hashtags and tags people uh i live for that you'll make me very happy so feel free to go wild uh so what are we gonna talk about for the next 23 or so minutes um we are going to talk about figuring out

what kind of documents to write how to write it where to put it once you've written it how to socialize it how to evaluate it and then what to do next and give you a little context for the kind of documentation i'm talking about here i'd say it applies for small companies up to companies of maybe 5 000 people basically just shy of where a company can pay for a comms team and a content strategist and the stuff i'm going to talk about is it's important there but it's less often that engineers are pressed into writing documents there so it comes up a little bit less but let's dive in first we need to figure out what we need

to write and for that we need to spy on our colleagues we're going to start by eavesdropping if it's safe for you to go back into an office that's amazing i used to love sitting in the middle of the office and just figuring out what people didn't know yet by listening to them talk for us a little more right now uh it is slack ideally you have a channel that's something like ask security that says hey people with security questions why don't you pop in and people are you know operators are standing by waiting to answer your questions and the great thing about this is it also gives you a place to collect those questions so you

know what's going on we also need to check views on existing docs confluence and google drive both do this in different ways a warning this can be gutting especially if you're the person who wrote some of the existing documentation to look at something that you remember spending two weeks on and 17 people have looked at it but the thing is we need to know or else we're not going to do this right we also need to talk to people who depend on this work who will be honest with us ask them are the docs out there are they written the right way are they covering the right material where are the gaps people can tell you where you need to

start we also need to learn from the past and incidentally this is what i think of whenever i hear the phrase pick your brain i think it is very gross but i like this picture a lot so learning from the past if we can talk to the person who's responsible for all the existing docs before which might be you but if it's not you want to go and just get a sense of what has transpired and if that person's no longer there try to figure out why that is because that might also be very instructional we also want to figure out what docs have people traditionally shared and also just as important what docs have

people not shared what do people not know exist and why do they not know it exists when it's out there in a way that someone thought it was accessible and able to be found basically we want to get a sense of the efforts of old and what's been done because uh one thing that humans and engineers have in common is if we don't learn from the past we will repeat it to death and keep screwing up and while we're at the planning phase remember to pace yourself this is not a task where we're either trying to drink the ocean nor boil it and the great news is that when we start putting some concentrated specific

effort into this people will notice a little effort goes a long way if you put some love into something that has been a problem for a while people will recognize it and be pretty psyched the other good news we are not aiming for perfection uh documentation is by its nature a fairly subjective uh thing that we're undertaking so there's no way to get 100 this is fantastic the other thing i recommend just to not burn yourself out i like pursuing two questions at a time this way you're not trying to answer literally everything with every bit of research you do and also it lets you find interesting connections between things um way more than if you were going very

single-mindedly and being like today is only for this question and everything else must be ignored so to recap how do we know what to write listen to conversations read the chat ruthlessly exploit our colleagues good natured communication for our own devices uh check stats on existing documents just so you know what is actually being used and how ask around to see what's actually working and what isn't and as you go through stuff just work to answer two questions at a time once you answer one you replace it and you keep on so now that we have a sense of what to write let's talk for a minute about what it means for a document to be good

i promised you x so it's a good document what enables people to carry out the behavior that we want from them it's not uncommon for docs to be like this super cute very well intended definitely the cats are going to work this way kind of food dish design where you think it's doing one thing but actually something else comes out the other end but it's okay we can get past this we can get past this by building a better document and one of my favorite ways to do this is by including everything that you can i've just read way too many tech documents where just you know this command or this detail gets left out

because there are assumptions made about the reader that fundamentally don't work so if you know something just put it in there there's no reason to withhold its commands it's file locations steps all sorts of stuff just put it in there because if someone's trying to figure out what you're already trying to figure out they need to know the same stuff that you do we also want the dock to be a complete resource imagine there was an ill-fated off-site and everyone succumbed to food poisoning or kovid you know we're writing for the survivor we want to get sigourney weaver to safety and alien with our doc we want to tell her everything she needs to get

this done and make things okay and related to that because it's not rare for a security doc to be talking to someone on a pretty rough day of work docs need to be friendly by which i mean not adversarial it is important that the person reading the doc feels like the doc author is rooting for them we have to be the people's cheerleaders and to bolster that docs should not use a vocabulary that's different than the user we need to speak the user's language and if we introduce new things we need to explain them either by expanding in a parenthetical linking to something we just need to get them to where we are to that end

we need to be really targeted so for every document i write i have this at least in mind if not written down i am just writing this doc for this audience to describe this information for this purpose so for example i'm writing this doc for our front-end engineers to describe our preferred form libraries to avoid cross-site scripting it tells you what's in there you get a pretty good idea of how it's written and you have an idea of maybe what is out of bounds and not so relevant or a little more ambitiously i'm writing the stock for everyone to describe common fishing techniques for thwarting recent spear phishing attacks that's a different vocabulary a little hard for right

or i'm writing this doc for that executive and if you've had that executive i think you're picturing them right now you know to describe why we need this tool for upcoming budget planning so who are you talking to what are you trying to accomplish it's great to write this at the top of the draft when you get started just so that you don't drift then you write it and you ask that person that you decided to aim for if this actually enables them to do what they need and if not it's time to iterate so to sum up how do we know a good document when we see it it includes everything a person might need to know

about the subject or process to get their job done it's friendly speaks the user's language and it has an intended audience information to be conveyed and a stated purpose for existing and this is how we know if we've hit our mark or not so we know what to write we know who we're writing to how should we write it for that i have the perpetual security answer i'm afraid it depends it always always depends there's so many possible kinds of docs your purpose will determine what you need to write so for example docs to solidify process you know playbooks you had a thing happen here's what to do maybe you got pii in the logs common stuff here's what

you do here you list out steps here's who you talk to here's what you need to change here's what to do to make sure this doesn't happen in the future with these especially expect to refine it a few things a few times especially if you're writing for people who aren't familiar with this stuff but are suddenly immersed in it process docs describing what a team does describing something that people need to do from start to finish and these can be either rarely used but really still important or frequently used and you'll get a lot of information about it from people and this kind of dock includes process flow charts which i will confess i have a bias i kind of

hate them because they often seem like the first last and only resort of attempting to convey information from teams that don't actually want to help you and mostly they kind of wish you'd go away so if it's the first thing a team throws at people i get kind of leery they i just don't find them as accessible as people think especially if it's a rat's nest of overlapping swim lands kind of like this nightmare this is what i found on google when i searched terrible flowchart so just imagine you have a task in front of you and a team just said oh yeah just check out our flowchart you'll be fine and then they hand you this

they hate you and this is what we're trying to avoid and if you must use one of these and there are legitimate reasons sometimes visual things are very useful ask someone off your team who will depend on this flow chart if it works before you release it because otherwise they're going to be big opaque parts that will read as very adversarial and that is what we don't want to happen okay this is the word you slide i usually avoid this but it's this nice grab bag of how to write tips so i just wanted to bundle it together for easy pictures if one is inclined so keep it friendly like we discussed aim for informal language it's best just

because a lot of people i don't know if you know this have bumped into really unfriendly security people and sometimes our job is to work to undo that and this is one way like we said explain all abbreviations and acronyms on first use sometimes more than once if the document's kind of long and while you're doing it link generously both internally to other documents also externally we like to reward the people who learn really deep and you already looked at it so why not just link it because you know which the good resources we want to make it clear who is behind a dock this helps just so that it deanonymizes things tells people who to

reach out to if something's not going so well we also want to chunk information with headers because some people like to skim some people command f their way through life i do sometimes totally valid and we want to support that there are lots of different kinds of readers and lots of situations related to that we don't ever want to assume someone's going to read the whole doc yeah i know we we make them lovingly we pour all of our word smithery into it sometimes or you know some of us nerds do but you can't assume that everyone's going to take in your entire beautiful efforts and that's all right um and related to that a doc has to work

separately of any supporting material sometimes it doesn't make sense to make a beautiful interwoven suite of documentation to get people to a higher goal but most likely they're just going to look at the part of it they need to get their ticket done that afternoon and that's the end of it totally okay if you're worried about attention spans and it is something that people need to read from start to finish do not underestimate the power of animal pictures and gifts it gives people a pause it's a relief sometimes in the middle of a bunch of technical language hello have you seen an axolotl lately maybe your soul needs it that's something that we can give

and finally include how to give feedback in every document this can be comments a link to chat a survey something like that we just we want it to make we want to feel like it's going two ways people are not reading this in isolation they can tell us if stuff's working or not and it's really important and worthy is slide so how do we write a document first you have to know what doc you're writing based on the purpose you figured out remember that your job is to explain but also to be approachable in words act like each doc has to exist in isolation because at least sometimes it will have to and make it skim friendly for people in

a hurry so now we've written it where do docs live we are trying to avoid the digital version of this which i suspect most of us have seen some version of it has been my experience that there are always at least two doc repositories google drive is often one just because so many people use g suite it's just there and people are accustomed to it sometimes it makes sense to put things in both places probably not though so we just have to figure out which one makes sense is the go-to resource for people in need and then aim our stuff there we also keep chat in mind chat is not documentation but it is a very live

information repository so just keep in mind how things get shared it's sometimes going to be your job to share it in there to get the job done and we have to keep in mind that governance works differently depending on where you end up putting your docs how do we indicate a draft versus a final version for instance it all depends on where you decide things need to live so we can learn the stuff through observation and asking or we can learn by trying something getting it wrong and being corrected and most likely this is going to happen but that is great that is information and is what we need we also have to get a sense of a sense

of how people look for information like are they reliant on docs uh that are linked at the top of channels do they usually go searching and this is something you really need to figure out at this point because it's going to play into the next step so are they searching in google drive are they searching in confluence do you know does the title of the doc match the vocabulary so going back to something i said earlier the stellar thing i promise you're not going to find a perfect solution here and if you find yourself ready to suggest the perfect document repository that you used your previous job if we can just buy it and bring it

in it's going to solve all of our problems uh stop don't do that um i want you to remember the joke about now we have 24 javascript frameworks it applies here too throwing more places to put information in is not supporting our users instead you're looking for like a 75 solution this is a very seize gets degrees kind of situation in our case the c is consistency just whatever you do just pick it and stay with it and it'll be really tempting to like oh if only no no just stay with it and then you want to get actual information from the people depending on it before you change course when you do communicate it and solicit

feedback so yeah putting docs in the right place we want to figure out all the places docs can live figure out how and where people tend to search figure out how they search um match it when you can especially at first and then stay the course until you have reason to shift so yeah now we're at the socialization part let's get your work out there which means you have to talk to people i'm afraid sometimes people end up in the putting words in a doc work because they're not thrilling you know thrilled to this but sorry it's what we have to do back to chat surveillance and participation this can be automated stuff it can also

be just kind of haunting everywhere engineering team channels security channels sometimes off-topic ones too we're looking to see questions come out even if they're not actually phrased as a question we just want to be ready to give the answer that's needed when the question arises then there are meetings which i know we have lots of those and i'm telling you to have some more sorry it's very effective though i like going into team meetings and coming in with a document that lets me answer questions that have been asked before it's very useful to be able to see when people light up when you actually got the details right in the thing you decided to make

and even more efficient is if you can get in those all hands all engineering all companies stuff like that if you just snag a few minutes and you can promote what you did so that everyone has that first knowledge and first touch of what you've been putting your time into and if all that fails we're going to bribe people this is all cux it is okay to bribe people toward the behavior you want especially when it comes to security because this is really important one of my favorites because it is cheap and delightful is stickers and to that end we're going to do an experiment if you find me during the conference and i'll be here all day tomorrow and tell

me one thing that you learned or liked from this talk i will give you a security 8 ball sticker and i will not pass this out outside of b-sides so this is for us and for you when you go like hey i think i see that pink and purple lady haired lady and you come over you too know that your behavior can be swayed so i'll see you later [Applause] yeah also good um badges people like flair give them flair rewarding ambassadors by talking them up is really good give people public kudos have a way to give public kudos that's a really good idea to talk people up to their managers stuff like that coffee even though coffee is free in

offices and in the bay area is often quite lovely actually something about being enabled to go and get a treat is really effective because the thing is it's not about the monetary value of this like giving bonuses is above our pay grade we don't get to do that what it is is making a compliment and appreciation more tangible and memorable and this stuff is really good for that because it's going to take some time and i'll just read this to you unfortunately the dry principle which is don't repeat yourself often a good principle in code does not apply to humans people need repetition as well as the same content applied in different ways people don't learn math from only an

explanation or only a textbook or only examples it's everything combined and that's what we're working with here you're gonna have to repeat yourself and it's completely okay people don't pick up on this stuff sometimes at first exposure they need to hear about it when they need it so it's more like you mention the doc and then it gets brought up in slack and then someone says it in a meeting probably you a link from a colleague if you feel self-conscious about repeating yourself which most non-tedious people do make a calendar and then you can just do it on a schedule you know exactly how much you've done it you can't imagine it that it was way more

and then you have a sense of what you're doing so it's much easier to iterate so getting work out there promote where the people are chat meetings all hands get comfortable with repeating yourself totally okay and if nothing else bribe people into the behavior that you want so how do we know our efforts are working you know do they even like me do they like our talks the great thing is because we are doing this we are all winners it's great it's low stakes we did the thing now we get to see what to do next so to evaluate we need to ask people regular check-ins one-on-ones do surveys you don't want to overload on these some people have had

bad experiences just make them regular short to the point check your metrics again and finding a goal person is really good and this can be a persona but also just literally like emily on the next team someone who has a bunch of needs that are unmet in documentation who you can check in with regularly and say you know is this doing it or do you need something else we also need to review regularly a quarter quarterly is good for it if that makes some dread curl in your stomach it can be biannually just as long as it happens in a regular cadence and happens and that's where that feedback comes in if people are regularly able to give

like a thumbs up or thumbs down in a document or add a little comment this gets way easier and a little note there are cultures that don't have great psychological safety and that can mean that when you say hey tell me what you think about this doc it can feel like a trap and that is unfortunate uh changing that culture wide probably also above our pay grade but we can make a little bubble of psychological safety by asking repeatedly making it clear we want an opinion on the document not our value as a security engineer not my team's value just the document and whether it meets the thing it's trying to do and if you keep doing that and you

people see that you take their feedback and actually act on it they will become gradually more forthcoming it's tough but we can't do this work unless people actually tell us this information after that ask around again determine your needs and map your future because we're trying to avoid this this was at my bart station recently and while i leveled maps and find this adorable if i were lost and saw this i would be terribly upset so we need to be on top of this stuff it's measuring success do your surveys talk to people get a sense of what you're doing review stuff regularly create at the very least a beautiful little bubble of psychological safety

around you and your documents and then start the next cycle so here's what to take with you as you go back out into an actual physical security conference that we're all at meet people where they are friendly language explain anything that they might not have bumped into before um maybe this means sometimes meetings instead of another confluent stock and sometimes it can mean gifts instead of code snippets depending on what your goal is you have to be creative and try to meet people with their weird needs keep different readers and learners in mind we are a good beautiful varied group and we want to talk to everyone channels we want to learn cultural norms what

they need so find channels about communication just get a sense of how people speak where they ask questions what they need to know see what people link and read and then match and then iterate and finally please do not burn out we are at especially high risk of that right now and i don't want that to happen to any of us so only answer two questions at a time know who you're writing to sometimes cultural norms are great sometimes we need to change them figure out which one is which and recognize your limitations and know that you can do wonderful amazing things inside of them thank you very much [Applause] all right thank you brianne for that

talk um we had two questions on slido but there might not be the time but um i'll read out the questions and we could answer it afterwards um sounds good thoughts on using github as documentation repository with plain markdown formatting good strategy or too limiting it depends on who you're dealing with there are some really beautiful ways that markdown can be displayed and again it's just consistency if people know to look there even if they're not people who will need to be able to like submit a pr to update stuff yeah i've seen it done really well there's no reason that can't work especially if you understand that different teams have different comfort with that kind of thing

all right uh thank you brienne for presenting a b-size sf on behalf of the conference and the support of our speaker gift sponsor matego we want to give you this token of our appreciation thank you thank you so much come see us at 3 p.m get a signed book