# The Secrets to Compelling Technical Writing - Jeffrey Scholz | RareSkills

- Channel: [ETH Belgrade Community](https://streameth.org/eth-belgrade-community)
- Date: 2025-10-07
- Duration: 18:13
- Topics: People & Blogs
- Watch: https://streameth.org/watch/yt-U9qWv0gfbLU
- YouTube: https://www.youtube.com/watch?v=U9qWv0gfbLU

## Description

The Secrets to Compelling Technical Writing - Jeffrey Scholz | RareSkills

## Transcript

All right. Um, hello everyone. I'm Jeffrey. Uh, so just to make sure I, uh, speak at the right level to my audience, how many people here have a coding background? Okay, the majority of you. Uh, how many of you are familiar with Rare Skills already? Okay, cool. So, Rare Skills, for for those of you who don't know, we're a developer education platform in Web 3 and we're focused pretty much exclusively on content that's directed to developers who've been around for two years plus in web 3. So, most of what we're known for is producing content that's easy to understand and breaks down hard subjects. I think one of our most known resources, how someone from a non-mmathematical background can create zero knowledge proof algorithms from scratch. So I I want to share a little bit about you know how do we do it because content is something that's largely published and then forgotten. But I'm pretty proud to say that people remember us when we produce content on a subject and the articles have value that lasts years beyond when they were originally published. So I want to share some of what goes into that. So there's a lot of definitions for technical writing. I'm just going to use uh this one. At the end of the day, what you're trying to do is you're trying to save the reader time. That's where the where the value comes in. That's how you are essentially giving a array uh undertaken. There's a very interesting autocorrect over there. Uh essentially what you're doing is you're giving the reader value by saving them time. And that's you know time is money. That's where the writing can become quite valuable. And I think that's the ultimate metric by which it's measured by. Now, not every writing genre is uh evaluated on on this. For fiction, it's how how entertained are you? For political writing, it's how persuasive are you or how how much does your writing influence uh the general society. But in technical writing, the optimization goal in my opinion is saving the reader time. So there's really it really breaks down into uh three things how I like to conceptualize creating good writing. The first one is that technical writing inherently has a very narrow focus. If you're writing on say how to create a smart contract on Cosmos ecosystem, that's there's a lot of people who are not interested in that. And that's by design. If you create technical writing that's designed to appeal to a lot of people, chances are you're doing something more along the lines of edutainment or uh just, you know, trying to create attention, which is fine, but you just want to be conscious in technical writing. there's a specific audience with a specific problem. Um, seems like we have a font issue here. That's okay. And once you've established, hey, my end goal is, I'll talk more about goals specifically in the in the next section, but my end goal is to have a certain outcome. I want to develop my contract on a certain ecosystem. I want to be able to do a security review on a certain kind of uh product. Now, which remember how I said technical writing is about saving the reader time? that's heavily correlated to how much effort they have to put into it. So if you if you wanted to learn about a relatively advanced subject like let's say how does uh the plunk algorithm work in zero knowledge proofs there's already material on that you can just read the original academic paper but that's not a loweffort way to read it for a lot of people so we'll we'll talk about minimizing effort uh modulo a certain goal and the third one that we'll talk about at the very end which is uh we won't spend that much time on that's what we typically think of as uh improving our writing you know when proof reading someone's writing, you're looking for mistakes or things that sound a little off. Uh what I'm going to talk about in this uh talk is that the typical polishing that you would get from putting your writing into something like Grammarly or having a proof reader look at it and jump out at mistakes actually really only makes up a small fraction of what makes technical writing good. Okay, so setting a goal. I'm I've the best way to illustrate this is by just giving some examples really. Notice how I I've labeled this as bad. I'm going to teach a certain programming language, Solidity. Well, who are you going to teach it to? How much of it are you going to teach it to? Does this person already know how to code or not? Uh the goals need to be specific because how can you know if your writing actually accomplishes its goal if the goal is not even stated to begin with? I would say this is probably the most common mistake I see with people who are writing is they oh, I need to write on a certain subject, but they if you ask them what the goal of their article is, they couldn't even state it. So, uh, if you don't know the what the goal is, how can you know if your writing is any good? So, I've given some examples that are more specific. So, like I said earlier, an article is by design not for most readers. It's supposed to solve a few specific problems for people in a specific situation. Well, now this does contain some technical terms in here. So, um, you know, I'm not going to explain it to everyone where we have since we all have different backgrounds here, but hopefully it illustrates, um, what a good goal looks like. Something that I want to summarize out of all of these goals is that there's a target audience, a subject, and an outcome. So, let's let's use an example. Uh I want a senior blockchain engineer to be able to code a goth 16 prover and verify from scratch without using a zk library and while keeping the math minimized. That's one of the that was the inspiration behind our zk book. So the who is a senior engineer, right? The the way you write to a senior engineer is not the same way you write to a junior engineer. Uh what well we're we're teaching a certain subject which was a zero knowledge proof algorithm. And what's the outcome? Well, it might seem like okay, so that they learn uh the algorithm. But what does it mean to learn the algorithm? Is it just so that you have a conceptual understanding of it? Is it so that you can produce code in it? Is it so that you can uh write more optimal versions of it if you're trying to make your code more efficient? These are all not the same outcome. And your article can't optimize for all of those goals at the same time. So, you need to pick one. uh something an important distinction that I need to talk about when I do a goal especially in the subject of technical writing is uh the distinction between between procedural and conceptual so in a lot of programming tutorials like let's say how to run a a a local node of uh starknet on your computer or something like that well so the reader might not be interested in what okay well what are the entry points of the client and whatnot they just might say okay just give me some clear instructions for how to set it up so that's that's procedural and uh conceptual. So again, it's important to come into the goal, are we just trying to tell someone how to do something or are we trying to help them understand this subject or a hybrid of the two? And another reason for that is if someone is coming into your article with a mindset of, hey, I want to have a certain outcome by the end. Uh and you're going off on a lot of tangents explaining, okay, why is this step this way? then they're not going to be happy about that because you're increasing the amount of effort that they need to put into reading your article. Whereas someone who's trying to learn something won't be happy if you omit that. So again, you you want to be clear in your original goal if you're doing something conceptual or procedural. Um for those of you who are familiar with our works already, I'm just going to gloss over this. Uh there's no correct answer for if you should be procedural or conceptual or some combination of the two. Uh sometimes one informs the other. If you give purely procedural, people won't know how it works. But if you're purely conceptual, uh, a lot of programmers learn by actually doing things. So, if you're just giving a bunch of abstract definitions, they might not really appreciate that. Okay. Um, here's just some more examples of that. I'm going to skip through that. Now, let's talk about how we can minimize reader effort. And this is tricky because generally, uh, the shorter your article, uh, the less effort it takes to read. But on the other hand, if your article is short because it contains a bunch of a bunch of dense math notation like a typical academic paper does, then that's not as little ef effort as possible. So purely the length of the article is not it's important, but it's not the only thing. So let's uh sorry there I'm not sure what what's going on with the fonts here, but that's all right. Uh what what does it even mean to understand something in the first place? If you're try if you're just giving a purely procedural thing, that's pretty simple. Just give steps one two three four five six. But if you're trying to help someone understand something, what does it even mean to understand something in the first place? Well, uh this is okay, this example that I have here might not make sense to about a third of the audience here, so I'm just going to skip over it. But let's say that you're you're undergo undertaking a project and you want to build like a apartment building. Well, what what does it even mean to understand what know what goes into an apartment building? Well, you have to understand the regulations that you have to uh comply with. You have to understand the marketing that goes into it. You have to understand uh any building codes that you need to adhere to. So forth and so on. But if someone just throws a bunch of facts at you saying like here's a bunch of true statements. You need a permit from this department. Uh you need to have this certain occupancy level in order to make your finances work. Blah blah blah. Nobody remembers if you just throw a bunch of facts at them. That's very uh people's minds don't work that way. So what's important is that as the facts are introduced this is I'm using a different example because the one I'm using now is slightly less technical. When the facts are introduced it needs to fit into a mental framework that the person already has. So you you can't just tell them hey here's all the true things that you need to know. You can hack a smart contract if a um you know some access control is missing for example. But okay, well why do we even have access control on some functions and not others? Those are uh those are so you can't just say oh it's insecure because access control is missing. People need to understand well why is it even needed in some in the first place and not in others. So I like to call this a uh knowledge graph. Um, and one challenge that can be I'll talk more about the knowledge graph in a second, but one challenge that arises from uh trying to present the information is if if you're already an expert on a topic, you probably know how all the fat facts fit together. Okay, Docker is a a virtual machine. Why do we have virtual machines? Because uh well, we want to have install the dependency seamlessly. So, these are all things that you know intuitively, but often times you may find when you're trying to explain something to someone uh there end up being gaps in your explanation. them. Sure, we've had professors who really knew their subject, but couldn't know what they were talking about. Well, that's because the knowledge graph was encoded in their head intuitively, but they didn't have a verbal encoding for it. And uh a lot of writing is really just translating an intuitive understanding into a verbal encoding. And that's really what makes it tricky. So, uh this is basically what I'm just talking about. Uh you may know the facts and how they fit together, but that's good for you. For a good writing, it needs to be explicit and encoded verbally. So, um, when you look at these paintings, uh, who can identify the the artists of maybe the one over here, the one on the far left, or maybe any of them? Okay. Yeah. What what which can you identify? >> That's right. Uhhuh. Andy Warhol and Pablo Picasso. >> Yes, that's right. One go. And the >> That's Pablo Picasso. Yeah. >> Last one. Uh >> that one's a little trickier. It's Pete Mandrean. Yeah. >> But how how did you know that? >> Well, I know it for some long time. >> Right. So, when we look at this art pattern over here, we kind of know like, oh, yeah, that's that's something that Van Go would do. a painting of like objects from this era. That's something that Warhol would do. So these are all we have the facts to like the facts are in our head, but if you were to describe to somebody who hasn't seen these paintings before, how can you identify the paintings? That would be very hard to do. But that's the goal of technical writing and that's why it's hard. I mean, a more subtle challenge is some people write when they don't know what they're talking about. I think this should be kind of obvious. If if you don't know how to identify these paintings in the first place, you're not going to be able to tell someone how to do it. Um, I'm not going to belabor this point, but obviously I need to state it because some people write on a subject and they fool themselves into thinking that they understand the subject when I they don't. So, it's important when you're writing to have some sort of a built-in feedback mechanism that tells you you're doing it wrong. Uh, this quote I have up here is from one of the people who works at Rare Skills, so I'm just attributing it to him. Uh but at least in my experience when I'm writing about a technical subject I need to either write a math proof for it or write some code that really forces me to understand the subject because the nice thing about math proofs and code is uh if they don't work then it's clearly my fault. So it forces me to correct my understanding. Now there's no guarantee that this will work a lot all of the time but it covers a lot of cases. So um the first step is make sure you can actually pass the test. Can can you actually do the t can you actually do the test? Do you have a mechanism to get uh to to figure out if your understanding even works? And then the next step is turning your understanding into a verbal encoding. Okay. So, um let's get back to the knowledge graph thing. So, there's a bunch of facts that go into understanding a subject. Like, let's go back to the paintings. There's a style of painting. There's a maybe a certain set of colors that the author tends to use. Maybe a certain kind of brush. Um so, you have to get all of those facts down. But like I said, if you just give people a list of facts, then they're not going to remember it. Uh when you introduce facts to your reader, you want to be conscious. How does this relate to everything else that I've talked about before? And this is hardly an exhaustive list. But um okay, let's let's go back to our building example. Well, before we even talk about building codes, you probably if the building code talks about material that you're going to be using, like a certain grade of concrete, then you need to understand what grades of concrete exist, right? So that would be a prerequisite. Uh co-requisite is a circular dependency. I think these should be self-explanatory. I'm not I don't have time to get into all of these in detail, but you want to be thinking what's the relationship between the facts I'm introducing so that uh the reader has a way of fitting what you're saying together. Uh who here knows how to program in Rust? Um okay, a few people. So I'm just going to skim over this. For those of you who are thinking about writing a Rust tutorial, uh here's a bunch of things that are true about Rust. You can't use a variable after you take it. Variables have ownership. Uh and references and cloning kind of solve the same problem, but not really. Uh so when you're introducing it, you could say, "Hey, look, here's a bunch of facts about Rust." But you also want to be conscious when you're introducing the facts. How do they relate to each other? And that determines the flow of how you're going to write your article and how you're going to introduce the next subject. Uh this is the knowledge graph for uh ZK. It's similar, so I'm just going to skip over it. Um so the beyond just presenting uh how your facts connect to each other, I think another common mistake I see very frequently in technical writing is not being explicit enough about what facts you're introducing. So when I see LLMs doing writing or people who don't are not super confident in what they're talking about, they say an account does this. A re-entrance guard essentially is this. A crosscontract call is basically like or similar to see the these are kind of weasling your way out of accidentally saying something imprecise. When people do stuff like this, it's often times an indicator they don't have a complete understanding of what they're talking about or they're too afraid to put their foot down. So I like I some maybe I might call this dancing around definitions, but when you introduce the facts, you need to be very confident in what you're talking about. Okay. So um I'm just going to skip over this. And the thing with in with introducing facts is you generally want to introduce as few as possible because the more you have the more it overloads the reader. And once you've I think one of the hardest thing that goes into writing is which facts am I even going to present in the first place? And then once you pick that, how am I going to tie them together? I'll jump over this. And then the final thing is once you have a good knowledge graph, you you state your facts clearly um and you figure out how they all tie together. The writing can still be helpful but not quite there. And uh you might see, okay, well, what's the difference between these two images? Well, one you have something valuable underneath all the dirt and the other one you just have dirt, right? So even after you have all of some great uh engineering in into your uh writing, you still might need to clean it up. And that's where a lot of honestly an LLM can help you with a lot of these things. But you can if if you're working with a proof reader, you this is part of a checklist that we use to uh help our proof readers look for things that distract and get in the way of the information that's being conveyed. Okay. So first thing I would say if you're doing technical writing, start with a goal. Make the goal very specific because without that you don't have something to optimize against. And the way you accomplish that goal is picking which facts you're going to present to the reader, ideally as few as possible. And then it's very important that you are conscious in your own mind how those facts tie together and how they relate to each other. Uh and then once you have all of that then you can do what we typically think of proof writing which is uh you know just making it sound good when it's read out loud. So uh that wraps up my talk. I hope that it's helpful for any writing that you do. Uh rare skills we have our booth out there so please stop by and say hi. [Applause]