 Okay, awesome. Thank you so much for the intro and hi everyone. Welcome to the first talk of the second day of Norsak. I'm super bummed that I'm not able to join you guys at the event today and meet y'all. I'm actually currently under COVID quarantine at the moment. But so thank you guys so much for the opportunity to present this talk remotely. Let me start sharing my screen one moment please. Can y'all see my screen right now? Awesome. So hi everyone and welcome to, I thought writing a tech book was supposed to be fun. My name is Vicky Lee and I am the author of Bug Bounty Bootcamp, which is a book that helps beginners learn web security and get into bug bounty hunting. And also I write a security blog online and I also work as a technical writer for multiple cybersecurity firms doing things like documentation, tutorials and corporate blogs for a really long time. And the topic for today's talk is how do you write better technical content more efficiently? I think as security professionals, we probably all have the experience where we need to write some sort of technical document. Sometimes it comes in a form of reports from pen testing engagements or sometimes it's some sort of documentation that you need to write to document the tools that you've developed. So in this session, I'd like to first talk a little bit about the strategy that helps me write better technical articles more efficiently. And then so I'll talk about things like how to write better documentation, better guides and better tutorials. And then I'm going to go into how to write approachable and appealing blog posts online and how you can optimize for that experience. If you do want to start a technical blog of your own. And then finally, I'm going to go just a little bit into the process of writing a book. And if you do want to write and publish a book, what do you have to do and what kind of key decisions would you have to make. So I started writing technical content when I was trying to transition from development into security. I tried to learn bug bounty hunting as a way to learn more about web security. And what I would do is that I would go on to hacker one and find all of these disclosed vulnerabilities online and look at the vulnerabilities that they reference and try to learn about them. And I start spending a lot of time reading these reports and learning about the vulnerabilities for each vulnerability I want to learn about, I would search online for information. I would do tons of Google searches about SQL injection and read all the articles that come back in my Google search. And what I found was that there was tons and tons of content online at that time to learn about web security. But a lot of the times these blog posts only mention one or two very limited aspects of that topic or sometimes these articles can be sort of outdated or misleading in some way. So it's really, really hard to learn everything about a single topic as a beginner because it's really hard to get the big picture or the comprehensive view because there's no such resource online for beginners in that way. But I take SQL injection, for example, it often takes like 10 to 20 Google searches and reading every single article that comes back from these searches just to understand the big picture of how it all works and what someone can do with it. So I started to do a lot of research by myself, organizing fact checking and curating the information myself. And with all that Googling and organization, I started to accumulate a lot of notes that turned into a large repository of knowledge about web security that I accumulated while I was learning myself. So I thought, hey, I can turn this research and this content curation I've done for myself into a book so I can expedite the learning process for others. And this is why I started writing bug bounty boot camp. And the expectation before I started the book was sort of like, this is going to be an easy side project and I'm going to be done with this project within six months of working on the weekends. I was very innocent. The reality was that it took me nearly two years and over 40 hours per week of work to complete the entire book. So it was a giant, giant massive undertaking that I didn't expect. But no regrets, because I feel like I've learned a lot about web security in the process. I had a lot of fun. And I met a lot of interesting people because a lot of people in the security industry actually started reaching out to me once my book was announced. And I also really love the process of technical writing because it's a way of sharing knowledge. And you can share what you've learned and really use that to expedite the learning process for others without ever meeting them in person. I've had people reach out to me saying that we can help them learn web security for themselves and start hunting for bug bounty themselves. So I encourage low security folks to give technical writing a try because it's a great way of clarifying your own thoughts and helping yourself learn and understand a concept more deeply. And also participate in this sort of indirect mentorship and knowledge sharing using the time that you've already invested in research. But the one caveat is that writing is really, really difficult. Writing is really a specialist skill that a lot of the time are not taught to us either when we're in college studying some sort of technical topic or on our jobs. There's no really any formal training program that we can take on writing. And it's one thing to produce documentation and notes that you can understand yourself, but it's a lot more difficult to write something that can be used and understood by other people. So in this talk, I want to talk about how I make this process easier for myself and how you can optimize your technical writing process to produce better, more understandable technical content more efficiently. So I think writing is way easier. Oh, technical writing in particular is way easier if you break it down into three distinct steps. Research and outlining content dumping and editing. So let's get started with the first step research and outlining. This is where you're figuring out what information to include in your article, what information to not include, what sequence to introduce concepts in, and what structure of writing would be the best to present your information at hand. So I will first do research on the topic. I try to find out everything I can about the topic right even if I'm already familiar with what I'm trying to write about. I try to read as much documentation, blog posts, write ups and books about a technology. And just in general, collect as much information about a subject as possible just in case I'm missing some aspect of the topic, or that I want to enrich some parts of my article, right? I will make detailed notes during this process and organize the information I found. I also fact check everything I read about and test out all the payload and all the code to make sure that they all work. And it's really, really important to do all this research prior to starting to write because it helps you get the full picture of what you're writing about. And it also helps you with planning and thinking about how you can structure the content and best present this content to your reader. After research, you can slowly, well even during research, you can slowly start listing out the topics that you want to talk about and try to think about what a logical progression would be for your article. And this is where you get your first draft of outline. So here you can see like, let's say that we are writing an article that teaches developers what sequel injections are and how they can prevent it. You can start to list out the different things that you want to include in the article, such as how sequel queries work and how that leads to sequel injections. What are some types of sequel injection vulnerabilities, and perhaps include some real life examples of sequel injections that you've seen, and then include a section on how to prevent sequel injections. And it's important to remember that outlines, just like articles, they go through multiple drafts. And this outline can be changed and refined as you do more research or as you start writing. And this step often takes lots and lots of times, right? And I often find myself changing the outline or the structure of an article later in the writing process or the research process. So for example, you can add subtopics to refine the points that you want to touch on, or you can delete something that you think is too much for this article and perhaps move it to a subsequent article, or even break everything that you want to talk about down into a series. So here you can see that I added some points to my outline. And the outline is really becoming more detailed and is starting to provide you with a concrete direction for what you want to write about. Right. So you can see here that in the prevention section, we added parameterization so that you know that you're going to have to touch on that point when you are writing that part of the article. And most planning of the article should really be done at this stage before you start writing, because this is where you'll be deciding exactly what to present to the reader and how. And outlining and planning the article in advance this way will really help you write a more coherent article and make sure that you're not missing any important point that might be important for your reader to know. And once you have your outline ready, you can start going through your outline and filling out all the relevant information you have for each outline item. I call this my content dumping phase. I typically will have my notes from my research phase by my side, and then I'll start translating the concepts that I've learned during the research phase into plain spoken English. So think about how you would explain a concept like SQL injection to your friends and start dumping out whatever thoughts you have into either a text editor or on paper. And that's how you prefer to write. And all like all you're doing at this point is dumping content out right a very, very important thing to remember at this point is not to edit yourself when you're writing. I think a big tip about writer's block is that a lot of times when people feel like, oh, they can't figure out what to write or they can put anything on paper is because they it's caused by inhibition and the fear of their words not coming out right. So you don't want to censor yourself at this point. Simply capture all your thoughts that you want to express and don't worry about styling or grammar or even typos or anything that would affect the reader's experience. Those can all come later in the process. And it's very, very important to compartmentalize writing and editing, because you'll be able to write much more freely. All you're doing right now is to say everything you want to say about a topic and make sure you have all the content down onto paper or a text editor. But this also means that your first draft would probably be absolutely trash. Like my first draft 100 or 100% of the times is not something I want to present to my reader. Right, that's where editing comes into play. But we can talk a little bit about that later. Here you can see that we have an outline here from our previous step, and we can simply pick one item in the outline. It doesn't have to be you don't have to work on every single item in the outline. Like one by one, you can also skip to a certain outline item if you feel like it and start filling out information that you feel like is relevant for the reader at that point. And after you have the baseline of technical content ready. The next step is to ensure that your article is something that you can present to your reader. And that's when editing comes into play. And for editing, I typically do three types of editing in sequence. So I first go through a technical edit, and then I do what I call a common knowledge edit, and then finally copy edit. For the technical editing phase. This step is to ensure that both your text and your message and your images and your diagrams are technically correct, and don't contain any mistakes. And besides blatant technical mistakes, you should also look for things like technical contents, technical holes in the content. Are there anything that you fail to explain? Are there any logical jumps in the article? Or do you have anything that you need to rearrange to make it easier to read? Or is there something that could use more explanation or reference to another resource? And after you do a technical edit, the next step is what I call the common knowledge edit. And this is really the phase where you will try to optimize your article for the reader's experience. So in this phase, I try to read my writing as my target reader as someone with no prior knowledge about my topic and is instead equipped with the common knowledge for my target audience. So for example, if I am writing a security code review article for developers, I can probably assume that my readers already understand concepts like HTTP cookies encryption, but I shouldn't assume that they already know about how to conduct a security code review. And at this point, the technical content of your article is fixed. The next thing to do is to refine the words and sentences, so everything that we skipped during the last phase. So you can start deleting the content that don't add any meaning or clarity to your article, or think of ways of phrasing each sentence or each word better. Just in general, clean up the language and make sure that the article flows and makes logical sense and that it's easy to read. And then finally, I run my article through a grammar checker and read my article out loud or in my mind as a final sanity check that the article indeed flows and doesn't contain any last-minute mistakes. So that's basically the process that I take and the strategy I use to optimize my technical writing process. But now that you have a good framework for writing technical documents efficiently, a lot of people tell me they want to start a technical blog. I think writing an internet blog is very different from how you produce other documents, while the principles of good writing still very much applies. You have to plan in advance, you have to read your article as the reader, and you have to do fact checks and grammar checks. But if you want to write an approachable and appealing tech blog, there are two more principles to keep in mind to optimize your experience for the online reader experience. So the first tip I have for you to write an approachable blog post that people will want to read is to simplify and the next one is to keep things short and sweet. And what do I mean by simplify, right? Good technical writing is always easy to read, but this is especially true when you're writing on the internet. Because on the internet your technical blog post has the potential to be shared anywhere in the world, right? And you never know who will come across your content and what their background will be. And simplifying articles allow people like non-native speakers and novices to consume your article as well. And you want your content to be understood by the largest group of readers. And even if your readers don't have prior experience with your content and are indeed native English speakers, making your article simpler just makes it easier and faster to read by everyone. So try to use simple words and sentence structures whenever possible. And when you can explain something in one sentence, never use 10. Avoid things like jargon, abbreviation, acronyms, and obscure references. Because a lot of the times these would not be common knowledge for every one of your readers. So here we have an example of me trying to explain SQL injections. And it says that SQL injection attacks are a type of malicious activity that enables dangerous attackers to craft malicious SQL code to change the structure of a victim application. And SQL queries illicitly to steal sensitive data, modify confidential data, or potentially execute arbitrary commands in the underlying operating system. And you can see that this is an extremely long sentence with a complex sentence structure and a lot of unnecessary adjectives. And all that does is that it takes away from my main message and makes it difficult to understand what I'm really trying to say in this sentence. So we can instead rewrite the sentence as SQL injections allow attacker code to change the structure of application SQL queries to steal data, modify data, or potentially execute arbitrary commands in the underlying operating system. And you can see that the sentence is a lot shorter and more to the point. And as compared to the last sentence, it actually doesn't take away any meaning from the actual sentence itself. So this is how you simplify a sentence. And I know sometimes it's difficult to figure out how to simplify a sentence or a paragraph. And a good role of thumb that I use is to delete every single thing in a sentence or in a paragraph that doesn't help you illustrate or clarify the message that you're trying to convey. So as you go through your sentence or your entire article, you want to look at each component and really question yourself. Does this really help me say what I want to say or is this just fluff or does this even distract from my message that I'm trying to convey in the article. Another thing to keep in mind is that when writing for the Internet is very, very important to keep things short and sweet and to divide things up into chunks. So writing a blog post, it sounds like writing a research paper or a report because the way that people consume information on the Internet is different. When people are reading a blog post, they might scan the entire article for headers before committing a time to reading it. I know I do that a lot. And I might also be browsing Twitter or checking their phones at the same time while they're reading your article. Or they might be reading your article on the tiny, tiny smartphone screen. It's very different from the traditional reading from a paper or even reading an entire PDF on your laptop. So when you're writing Internet content, it's very, very important to optimize for a digital experience. So part of that is to divide your article up into easily digestible chunks and show that each section is marked with appropriate headers and sub headers. And this makes it easier for your readers to jump to different sections of your article if they do get distracted. And to just in general revisit different sections that they're interested in or share or reference different parts of the article with people online. Also try to keep things short and to the point to make your article more digestible during a short time frame. So if you're covering multiple topics in a blog post, you should consider chunking it up into multiple sections with headers and sub headers ready so that people can quickly skip to the parts that they're interested in. And another role of thumb I use when I am deciding how to divide things up in my article is one idea per sentence and one concept per paragraph. So I only try to say one thing per sentence and I also only try to explain one concept per paragraph. Don't try to say too much in one go. Keep your sentences short. If your sentence is getting too long, then you can divide it up into two sentences. If your paragraph is too long, break it down into multiple sections. And finally, if your blog post is getting too long, long as more than five minutes of reading, which is approximately 1500 words, consider making your blog post into a series of blog posts instead of stuffing everything into one single article. Because we probably all know people don't really have that long of an attention span on the internet. So it's important to make your article feel like it's easily digestible and very quickly readable. Yeah, short sentences and paragraphs also make your article much easier to read when people are using mobile devices and they don't have that big of a screen to work with. And I think so those are my tips for you for optimizing for the internet. But now that you understand how to write technical content, what if you want to write a technical book, right? There's a lot that goes into writing and publishing a technical book that's not just writing, but business and marketing decisions. And it's really a long and complicated process. In this presentation, I want to present with you a small overview of the process. I won't be able to go too much into it, but if you're really, really interested in writing and publishing a technical book and my experience doing it, feel free to reach out to me after the talk or via Twitter. And I'll be happy to answer any of your questions. So this is what I think the overall process of writing a technical book would be like. Of course, this process will be different for every single author, but this is what I think most author would need to do. Some parts of the process is like we just discussed, like you have to research your content, you'll have to structure and write the book. You have to work on the text, the diagrams, the code examples, and you have to work with multiple editors through multiple edits to make sure that your book is technically correct. But a lot of other decisions and processes that goes into writing a book doesn't really relate to the writing itself. Things like choosing a publisher or deciding how to package them, market the book. These are I think what traditionally we don't consider when we're writing blog posts or technical articles. And so I'd like to just quickly go through two key decisions that you'll also have to make that would impact your bookwriting experience a lot. And the first key decision that you have to make is deciding on the scope and the audience of the book. So with blog articles, you're most often just writing about a single topic at a time, right? But writing a book is different. When you're producing like a 300 page book or 400 page book, it's more like designing a college course or a curriculum. So you really need to think about who should read it and what they should get out of it. So a good strategy of doing that is to define broad but clear learning goals for a specific audience. So you can say things like I'm writing a book to help beginners how to find their first bug or I'm writing a book to help Python developers build dedicated security tools using Python. So defining these broad but clear learning goals will help you really decide what topics to include, what kind of prerequisites you need to require for your book, and how fast and with how much detail should you introduce concepts in the book. And another key decision that you have to make very early on the process is whether you want to use a publisher or not. Publishers usually help you with things like book editing and they coordinate things like printing, shipping and making sure that your book hits different sales channels. And they also help with some marketing and some PR tasks. And you don't have to use a publisher if you do decide to publish a book. A lot of people choose to self publish with great success as well. But the pros of self publishing is that you get to do whatever you want with your book. Publishers sometimes have certain styling or writing standards that they stick with. If you stop self published, you are in complete control of your book. And you also get to keep more of the profits. Usually when you work with a publisher, you'll get anywhere between 5 to 20% of the proceeds. If you self publish, you'll probably see more of that income. But working with a publisher means that a lot of the messy task of making a book is done for you. Things like finding the right editors, the right illustrators, making art and dealing with marketing tasks. These can be very tedious and really probably not in most technical people's expertise. So it just makes things easier if you do decide to outsource that to a publisher. And it's really a trade off of what you want from your book writing experience. And lastly, which publisher should you choose? There are quite a few publishers that specialize in tech. I honestly have to say that they are quite different in the way that how they work with authors, or how they edit books, how they draft their contracts. I'll be happy to talk more about it in person. So just reach out to me if you're interested in that. So to wrap up, technical writing is a great way to help you learn faster, learn more deeply, and help you share knowledge back to the community and mentor others. And a few takeaways that will help you write better technical articles more efficiently is first to write with simple language. You want to write as though you are speaking to really make the reading process a smooth and easy one for the reader. Second is don't write and edit at the same time. When you write and edit at the same time, a lot of the times you're censoring yourself and you're feeling yourself with inhibition and fear of your words not coming out right. So if you can compartmentalize these two tasks, a lot of times you'll be able to produce a lot more content more quickly. The third one is that you should always keep your reader in mind and really optimize for their experience when you're writing your article. Thanks and please ask any questions in Slido and if you have any private questions about this talk, either about writing, about publishing, about blogging, feel free to DM me as well on Twitter.