# Communicating Technology The problem is quite simple to understand. Engineers are educated to do engineering things. What are those things? Designing, running trade-offs, analyzing requirements, coding, testing, assembling, operating lab instruments, hitting things with hammers, and a long et cetera. Engineers are not educated to tell stories, write good presentations, have good grammar, and a rich vocabulary, and create graphical depictions that are intuitive and understandable by broad audiences. However, if an engineer happens to have these skills, they become a special kind of engineer, one who automatically has a comparative advantage compared to their colleagues and automatically stands out. Why? Simple: 99.9999% of the time, technology involves non-tech people in the loop: Investors, sales force, bid managers, consumers, and clients. ==Technology simply does not live in a protected crystal bubble, disconnected from everything around it==. Technology, sooner than later, must be understood by audiences who are not necessarily embedded in the specifics, and who are not even remotely interested in getting to those details. What is more, frequently, the true decision makers—the ones with the money, or with the power—are non-technical people. And that's when engineers with the capability of creating information and content that can be appealing, clear, accurate, and simple to understand—no matter its obscurity—become nothing short of essential. If you think this section is an ode to bureaucracy, think again. It's quite the opposite. We should write, as engineers, as few documents as possible (remember again Rams' [[Good Design and Bad Design#Rams' Ten Commandments|commandment]] number 10). The documents we write should be as short as possible. We should prepare as few presentations as possible, and they should be only a few slides. If this section is an ode to anything, it is to brevity, to clarity, and a humble attempt to help maximize the signal-to-noise and content-to-filler ratios. # Are You Not Entertained? Some time ago, I received an oddly satisfying compliment in a comment from a colleague who was going through a document I was writing at the time:  People don't expect to be entertained while reading a technical document. The question is: why? Why can't we be entertained while we read technical material? But we must observe the nuances here. Entertainment shall not preempt technical accuracy, which must remain our topmost priority. But why can't technical accuracy and entertaining text coexist peacefully? Writing entertaining content is, at the same time, entertaining to write. You as a tech writer are the first person to be entertained in a chain of people who will hopefully be entertained reading your material. There is nothing wrong with writing for your enjoyment. # The Obscure Art of Making PowerPoint Slides  Everybody hates slides, and yet we almost daily find ourselves in front of PowerPoint, or any of its alternatives, having to come up with yet another presentation.  We all daydream during presentations. What we usually do is to visually “sample” the presentation while we are doing something else: checking emails, reading slack, writing to a friend on WhatsApp, whatever.  Some people are fond of making 80-slide presentations, as if the amount of slides would be an indicator of quality or proof of work. Not sure if I even need to say this, but hear me out: if a topic is properly, intimately, truly understood, anything you need to say can be said in 10 slides. Fight me. Yes, even if you are preparing a presentation about quantum electrodynamics (I just randomly picked a topic which sounds complicated, although there is nothing really complicated about quantum electrodynamics), you can say it in 10 slides, or less. And if, for whatever reason, you feel you must go beyond that, you have probably not structured the topic or meeting’s scope the right way; in short, you are suffering from scope creep. An infectious disease amongst engineers.  What I am saying is that it is better to partition a complex topic into smaller chunks, compared to going for a marathon of slides that people will just ignore or daydream on. Life is too short to write unremarkable slides no one will remember. Conversely, think of powerpoint presentations as short stories, or movies. Because yes, making presentations is about storytelling. Storytelling means connecting ideas in a way they follow a narrative, stitching them in an attractive way. Storytelling augments reality by putting things together so they are more than the sum of their individual contributions. But good stories are brief. Time is king. Everyone is busy. Here’s some ugly news: nobody wants to read your stuff. That’s a fact. So, you better come up with a great story. You need to capture attention, and you have to do it fast. Attention is the real asset these days. So, better think of a solid story that will make them stop staring at their phones and feel they must look at your slides, or read your document. Your material must bring them to the edge of their chairs. Nice colors, logos and fonts help, sure. But the story is what matters. It has to be quick, clear, compact, and it must be awesome. But how do you do that? How do you tell a story? Well, just like Steven Pressfield says in _Nobody Wants to Read Your Shit[1](https://managerseverywhere.substack.com/p/the-esoteric-craft-of-communicating?utm_source=publication-search#footnote-1-96126976)_: like movies do:  > [!quote] > _Build the tension, and then pay it all off. That’s how jokes are told: setup, progression, punch line. That’s how any story is told. Have you ever tried to seduce someone? The hook, the build, the payoff. Theater works in three acts, Shakespeare as well. Do you know something they don’t?_ So, how to structure a presentation to make it compact as a short story? 1. Agenda: It doesn’t hurt, and the bullets can act as waypoints to connect the beginning with the end. Here’s a bit of an obvious tip: keep it short. No one really wants to see a 25-bullet agenda. The right amount? [7 plus-minus 2](https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two).  Another tip: don’t be afraid of being a bit spectacular on how you write those bullets. Nobody wants to read something like: - Requirements Review - Requirements Quality Assurance Process - Requirements Definition Methodology That’s a yawn-provoking agenda right there. I would run in the opposite direction. Consider converting those bullets above into something like: - Quick Recap On Top Requirements - Is Quality ‘Free’ As They Say? - Let’s agree the way we will work Or something like that. 2. Continue with something along the lines of the “_previously on…_” segment in TV series. Just like TV helps you recap what happened in the last episode or season, you must do the same with your audience. You may believe everybody is on top of the topic you are bringing up, but why would they? Are you so special? Everybody has a lot of stuff going on, so they might very well have forgotten what the whole thing was about. So, take one slide to set the context: what brought everybody here in the first place? What are the main issues to solve? What are the things everybody must remember before gearing up? Always kick off with proper introductory material, including the unavoidable basics—the things that must be understood if anyone pretends to get anywhere with what is coming next in the material. Imagine Walt Disney being randomly unfrozen[2](https://managerseverywhere.substack.com/p/the-esoteric-craft-of-communicating?utm_source=publication-search#footnote-2-96126976) and the first thing he does is to read your material: how do you start? 3. Build the tension: Now that everybody has been brought up to speed, start showing some substance. Point out the problems here. The conundrums. 4. And now, time to punch them in the face: transient is over, this is when the most important, the uncomfortable truths must be delivered. If there is an itchy point, don’t go too much around it out of politeness. Be clear, and direct. 5. Avoid links to external pages during the presentation. Avoid videos which create uncomfortable gaps in the presentation flow. ==Flow is essential, with flow understood as the smooth evolution in time of the presentation. No interruptions, no long pauses, no stupid questions to the audience that no one wants to pick up==. 6. Conclude, but don’t just summon Capt. Obvious: a conclusion slide only to repeat what you said some slides ago is utterly stupid. Conclude things that are truly conclusions. Take the time to process what you said and pack it in a digestible way. Say about next steps. Be receptive here on people raising eyebrows, this is the time for a good discussion and for reading body language. 7. Trash the “Any questions?” slide, with that annoying stock picture of the little figure with a giant floating question mark above his head. If your presentation was clear and provided good food for thought, those questions will naturally come anyway. If it was a yawning factory, your little guy with the question mark will not really raise the dead. 8. Incredible to state this, but always number your slides! People can easily remember a slide number and ask you to go back if needed. As opposed to the annoying “please go two slides back, no, no that one, one more, no, three more back”. Agh. Now, a few bonus considerations: - Always prioritize content before format. Have you ever read a presentation or a white paper from any of the so-called [Big Three](https://en.wikipedia.org/wiki/Big_Three_\(management_consultancies\))? Superb design. Great shadows of color. Stunning fonts. Everything looks so polished, so in place. Yet, the content is frequently utter bullshit. Pure hyped, MBA-originated fantasmagoria. The best presentations I remember had no template. Just white background, with black Arial letters. Granted, this could be a tad too rough for the eye, and some better visuals do not hurt, but the visuals should never come before the content. - You can be funny, but not too funny: the world is already full of great comedians. And humor is definitely a good way of breaking the ice. But ==adding one Dilbert joke per slide is just annoying==. That’s what separates comedians from us mortals: comedians learn to _read the room_ and can adapt their jokes as they go. Too many jokes are distracting, and while you might get a gentle expelling of air through someone’s nostrils for the first joke, you will only get cringe and silence after the second or third comic. If anything, and if humor is an unstoppable force inside you, Mr. Funny Guy, use your spontaneity and make those jokes verbally as you present. - Present your own shit. ==If you didn’t make the slides yourself, everyone will notice after 30 seconds of presenting.== Presentations are one of those things you just cannot delegate, unless you are a General Partner in some big consulting company, in which case it doesn’t make any difference because the presentation is probably pointless anyway. But tech presentations, that you simply do not delegate. - Go through your slides at the proper time. If you prepared the slides 4 months ago, you most likely will not remember what you put there, in which case you are in the same situation as the bullet above. Nothing as uncomfortable as someone having to take precious time to read a slide before presenting. A perfect flow breaker. - If for whatever reason you cannot present (your laptop was eaten by your dog, or similar), postpone until you get your setup right. Do not use someone as your slave to scroll slides for you. Slavery is illegal. It gives a horrible feeling of carelessness, and the poor person having to click slides back and forth does not deserve the pain. Next please! I said next, please. # Of Marketing Material and Turboencabulators Not long ago, I was somewhat masochistically watching a one-minute video of a salesperson from a tech company explaining the benefits of their technology. In an impressive sprint, the speaker motormouthed 16 buzzwords—one every roughly 4 seconds: *enable, proactively, leverage, engage, low-hanging fruit, win-win*, and many others I won't reproduce here so I won't start feeling nauseous. The whole structure of what this person said was a massively amorphous, unnecessarily complex ball of nothingness; it made, end to end, no sense. The speaker never answered the questions he was asked, and I seriously doubt it made anyone watching consider going and buying their products. There is an increasing lack of care for constructing concise meaning in marketing content related to complex technology. If feels as if saying the precise words, in their right amount, would've become something socially unacceptable, so we are urged to decorate our phrases with flimflam up to a level where the management-business-techno speak becomes the main subject and the true meaning gets buried under a pile of hyphenated rubbish. Time ago, a fictional electromechanical device called the Turboencabulator became a famous joke among engineers. Originally written by a British graduate student called John Hellins Quick and published by the British Institution of Electrical Engineers in their Students' Quarterly Journal in 1944, it represented the satirical marriage of technobabble and empty marketing, with memorable results. Throughout the years, other tech companies picked it up and continued the tradition. Here's the datasheet from GE for your reference:  And its specs are something special:  In its promotional video (see below), the benefits of buying the encabulator are thoroughly presented. Here's a transcript of this piece of comedy gold: > *"Here at Rockwell Automation's world headquarters, research has been proceeding to develop a line of automation products that establishes new standards for quality, technological leadership, and operating excellence. With customer success as our primary focus, work has been proceeding on the crudely conceived idea of an instrument that would not only provide inverse reactive current, for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument comprised of Dodge gears and bearings, Reliance Electric motors, Allen-Bradley controls, and all monitored by Rockwell Software is Rockwell Automation's "Retro Encabulator".* > > *Now, basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance. The original machine had a base plate of prefabulated amulite, surmounted by a malleable logarithmic casing in such a way that the two spurving bearings were in a direct line with the panametric fan.* > > *The lineup consisted simply of six hydrocoptic marzel vanes, so fitted to the ambifacient lunar wane shaft that side-fumbling was effectively prevented. The main winding was of the normal lotus o-deltoid type placed in panendermic semi boloid slots of the stator, every seventh conductor being connected by a non-reversible tremie pipe to the differential girdle spring on the 'up' end of the grammeters. Moreover, whenever fluorescence score motion is required, it may also be employed in conjunction with a drawn reciprocation dingle arm to reduce sinusoidal depleneration.* > > *The Retro Encabulator has now reached a high level of development, and it's being successfully used in the operation of milford trunnions. It's available soon; wherever Rockwell Automation products are sold."*  The sad reality has made the turboencabulator sound like a plausible product these days. The line between satire and "serious" marketing has thinned more than we should feel comfortable with. Technical content cannot succumb to market forces. Brochures cannot just become the vessels by means of which bullshit specs go around to attract careless customers. Because, at the end of the day, whatever you promise in your marketing material will need to live up to its promises, and that's when the engineers are called into the game. And when things tend to get ugly. Our humble fight, from the dark, deep trenches of the engineering departments, is to fight the urge to go full "turboencabulator" and actively police for consistent tech content to reach the marketing material. In his short essay titled Politics and the English Language (1946), George Orwell argues that there is a trend to think poorly because the language is in decline; and, as the language declines, "foolish" thoughts become even easier, reinforcing the original cause: > *A man may take to drink because he feels himself to be a failure, and then fail all the more completely because he drinks. It is rather the same thing that is happening to the English language. It becomes ugly and inaccurate because our thoughts are foolish, but the slovenliness of our language makes it easier to have foolish thoughts.* Basically: if you speak dumb language, your thinking becomes dumber which makes you spout even dumber language, and so on. Orwell also discusses "pretentious diction" and "meaningless words". "Pretentious diction" is used to make biases look impartial and scientific, while "meaningless words" are used to stop the reader from seeing the point of the statement. According to Orwell: "In certain kinds of content, it is normal to come across long passages which are almost completely lacking in meaning". Be careful; everything is in its right amount. Engineers can overshoot this and turn marketing material into overly specific, anodyne, hard-to-swallow technical bulletins no one will get. So, fair enough, let the marketing departments do their job: they know how to put things nicely so potential customers can feel curious about your products and make the fear of missing out (FOMO) creep up on them. Years ago, I was reviewing a proposal to be sent to a customer. As I was going through the pages, I remember feeling dizzy about the overall business babble. It was not only the buzzwords but also the childish aggrandizement, the cherry-picked metrics, the abuse of bold letters, the absurdity of the whole thing which—masochistically—I read from cover to cover. Of course, I had to say something. Long story short, not only the wording did stay, but the situation motivated a longer chat with the sales manager who said one of the most oddly flattering phrases has anyone said to me: — Ignacio, if our sales material depended on you, we would sell absolutely nothing* Fair enough. # Graphical Depictions There's a big, big problem in engineering that has remained unsolved for centuries: a depiction of two boxes connected by a two-sided arrow can mean anything. Anything. Depending on the context, it might be depicting two computers connected by a cable, two submarines torpedoing each other, or two charged particles repelling each other. Block diagramming is a no man's land and a largely unregulated practice. Let's stop acting like it's not. The thing is, it will continue being a total anarchy as long as we are given the immense freedom to choose to graphically describe things as we please. Which is a blessing and a curse. Perhaps more the latter than the former. The long-time-underestimated thing in graphical depictions is semantics. Semantics means what you understand from what you're looking at. When you see a traffic sign that is, technically speaking, just a funnily drawn, colored flat surface, what the sign means—its semantics—is unmistakable. A 'No Parking' sign means what it means, and there is no room for other interpretations. You know what happens if you leave your car in an area next to a sign of that kind because you know what that sign means and the implications of not following what the sign states. Well, some engineering diagrams are like traffic signs whose interpretation is rather open. The creator of said diagrams has a natural tendency to believe that everybody understands the semantics behind it, a semantics which only lives in their head. So, it might be a good time to bring back a postulate of diagrams that I wrote a while ago: > Block diagrams are only fully understood by those who drew them. > Corollary: there are as many interpretations of a block diagram as people in the audience. Conveying information in graphical ways is as powerful as it is tricky. An image can speak a thousand words, they say. But what if it can speak the wrong thousand words? This is not something graphic designers can help with; a bad block diagram is a bad block diagram regardless of how nice it looks, how many shades you add to it, or how 3D-looking the boxes are. Drawing good block diagrams is a semantic challenge, not a visual one. Now, a message of hope. It is possible to define solid rules for graphical diagrams. Electrical engineers, for instance, have devised very precise symbols and ways of graphically depicting circuits. These are called [[site/Hierarchy of Digital Systems#Schematic Capture|schematic diagrams]], and there is a very rich set of standardized symbols that Electrical Engineers use to describe their designs. Tools, both commercial and open source, have large libraries of such symbols inside which makes it very simple for an engineer to lay things out. Then, a schematic diagram made by subject A is understandable by subject B. Of course, you can draw bad schematic diagrams—we will see some examples further ahead—but at least the symbology is consistent. ## Form Follows Function? Not really I stop for a moment to digress a bit and talk about the physical resemblance of graphical depictions. For example, Electrical Engineers' standard symbol to depict a resistor looks like this:  > [!Figure] > _The standard symbol of a resistor_ But actual resistors, if you go and buy them in a store, look like this:  > [!Figure] > _A surface-mount resistor_ Or like this:  > [!Figure] > _Through-hole resistors_ As it can be seen, there is no correlation, visually speaking, between the symbol that *means* resistor and the way real resistors look like. The reason for this is rather simple: they do not need to relate as long as it is clear to everyone that the symbol shown above means what it means. Now when it comes to depicting the architecture of a more complex technical system, say, a satellite, aircraft, drone, or whatever, we must start depicting "boxes that contain other boxes that contain other boxes". Things can get more abstract, and there are no unmistakable symbols anymore because those boxes become very unique in their nature, so everything of that kind naturally becomes a generic "box" with a name in it. And that's when the interesting stuff (meaning, the semantic confusion) kicks in. The software industry did a funny thing, though. They became jealous of the rock-solid symbology the Electrical Engineers came up with and decided to create their own. Or kind of. So, the Unified Modeling Language (or UML) was born. ==As a side note: in general, anything called "Unified" tends to be a huge warning sign.== The adjective unified tends to describe an effort to consolidate disparate, disorganized, and even contradictory things together. Most of the things called "unified" tend to transpire as eccentric cocktails of sorts, and UML is no exception. But I will try to be objective here and just describe what it is. UML came to create a way of modeling software graphically. So it defined a set of diagrams, with their rules and semantics. This is a noble thing to do, except for the fact that software engineers were very lax in respecting said semantics. Years ago, I had the (bad) luck of attending a course on UML for embedded systems. The course started ok, but suddenly, the instructors started to mix up diagrams together, for example adding finite state machines inside a sequence diagram and connecting them. The travesty. I remember pointing this out and even getting a bit salty about it. ==The absolute whole point of getting consistent semantics in diagrams is about being strict on it. If we are not strict, then it just becomes a regular block diagram where all the postulates I listed above apply.== And, last but not least in this dissection of block diagramming, another uncomfortable truth: > [!note] > A block diagram is obsolete as soon as it is released ==The most painful part of drawing block diagrams is not about getting the arrows straight and aligned, but keeping them up to date==. Here's how the mechanics usually goes: 9. Spend hours drawing a block diagram 10. Paste it as an image in a document 11. Release document. Someone will print it on paper. 12. Something changes, block diagram goes outdated. Doc is now outdated. 13. Cringe in a corner because now there are multiple copies printed of your document with a block diagram which is no longer applicable and accept that you have become an involuntary soldier of the disinformation wars. Is there any hope? Yes, there is. Draw Better Diagrams With These Simple Tricks (Doctors Hate Him): - Assume no one will understand what you are drawing because they will genuinely not. - Do not try to resemble the physical form in a block diagram. There are better tools for doing that (CAD, EDA, etc.). Add screenshots or exports from those tools in case you must show how something physically looks like. An uncomfortable truth: Visio is not AutoCAD. If you still want to depict something (for example you want to depict a computer as a physical computer and not as a square box if, for instance, you are drawing a network diagram), use standard icons and images from the libraries. Do not draw a computer out of square boxes and circles. - Your arrows mean nothing unless you specify what they are supposed to mean. Arrows imply there is a link between two entities. Specify what that link means. It it dark matter? Energy? Power? A torpedo? We can never know unless you enlighten us. - Avoid obscure color coding unless you make the coding very explicit. If you thought that painting some boxes green to make a difference from some other boxes shared in pastel red would improve the diagram, think again. You might have just added fuel to the fire. - Ok hear me out: never, ever, under any circumstance, think of using spreadsheets to draw diagrams (yes, that's a thing I have seen) - Keep an eye out on the diagrams you have released into the wild and at least make some effort to keep them updated. Granted, if you drew hundreds of those, you will not be able to babysit each one of them anymore. In that case, hope for the best, but if you catch one, try to quickly say to the right audience that the diagram is out to date. - Have some minimum standardization of diagramming tools across your organization. - Make sure you have the original file of most diagrams out there. Nothing like a popular block diagram whose source file is gone forever, and you only have a pixelated JPG to live by and pass around. # Writing Does Not Bite There is nothing really dangerous about venturing yourself into the act of putting technical ideas together in written format. What is more, writing technical content is a noble task because it will most likely compound in time by helping people gain more insight into a topic of importance. Could be a colleague, a customer, a supervisor, or an investor. The act of absorbing and distilling information into knowledge can be a different experience depending on the quality of the content being consumed. If concise, accurate, and entertaining, riding a learning curve can be, in fact, enjoyable. It is reassuring to consume content that you can perceive has solid thinking behind it. It does speed up the whole process, because time just flies when you enjoy reading, as you go less and less ignorant by every paragraph, by every page. This crosscuts every scenario where knowledge and learners (of disparate avidity and quantity) mingle together: - Courses or lectures - Internal presentations to your colleagues to convey a new idea or project - Material for newcomers wanting to learn about technology the products the company they have just joined makes, or the ethos of the organization, its culture, etc. - Talking to investors for fundraising - Mentoring - Content marketing: creating technical material for potential customers to understand complex products or technologies - Documentation (internal or external): manuals, handbooks, cheat sheets, datasheets, white papers The sections below expand on some aspects of good tech writing. # The Power of Brevity (Kill Your Darlings) As we will see in the following sections, when it comes to transmitting signals over a physical medium like an electric interconnect, there are technical means to take care of the signal-to-noise ratio (SNR). These technical artifacts (power amplifiers, filters, etc.) work for us even if we are not looking. But when it comes to transmitting our ideas and concepts to an audience, either by a presentation, dissertation, documents, or emails, we are responsible for choosing the SNR ourselves, having access to both the numerator (signal) and denominator (noise) of the equation. No automatic artifacts are possible there, we're on our own. You would imagine we naturally seek to maximize SNR by reducing noise to near zero. But we easily tend to do the opposite. We say too much. We're chatterboxes. We love the addictive filler, the sound of our voices, and the look of our phrases. We state the same things over and over. See? I'm doing it right now. Word count and meaning have a strange relationship. Clarity and brevity are close siblings, but not twins. The sweet spot is when you can marry both: being brief and crystal clear. When I come across such a combo, damn it feels great. It's so rare. Get rid of filler. Remove. Cut. Erase. Discard. Drop. Kill your darlings. Form strategic alliances between words, do not just pile them up. Say less. Don't make a point that has already been made. # Disambiguation and Acronyms Recently, I had to read a technical manual about the 5G mobile communication technology. How did I tackle it? I got myself an almost intractable 600-page book. Let me tell you, 5G is an absolute miracle not because of the complexity of its technology (which is impressive) but because of the huge consensus needed to come up with such an impactful tech stack to be fielded globally. But, oh my, the amount of acronyms in that book was mesmerizing. In all fairness, it is not the authors' fault, but the folks behind 5G design and standardization. Ah, so you wanted to see the acronyms, eh? I knew you would ask. So, find them [here](https://pastebin.com/qCcsrm8F). Yikes. And I thought space was the industry of acronyms. I bet you have clicked the link and carefully read those one by one. Oh, you didn't? I am disappointed. By the way, I took the liberty to add an extra acronym somewhere there for comedic purposes, so go and find it. The book was practically impossible because, with so many acronyms, it was overly difficult to read and try to understand the topic while having to go back to the list of acronyms (which was also not hyperlinked) so then I had to memorize what page I was, go to the table, see the acronym, and go back, only to repeat this process like 50 times per page. What is more, the list above is especially tricky because it has nested acronyms! For example, see where it says SU-MIMO: it means it is not enough to go and search for one acronym in particular, but you need to then jump to find what the MIMO part of the acronym inside the acronym means. You can suffer a genuine mental stack overflow. Avoid at all costs something like this, think of your poor readers struggling to stay afloat. On a positive note, most likely the technology you are dealing with is less complex than 5G. If not, I pray for your soul. # Tone Content can use a colloquial tone (except when strictly required otherwise). Unless you are writing for His Majesty The King, choose a tone that reflects closeness and not distance or coldness. Avoid consistently trying to make the reader aware of your erudition. If you are truly smart, you probably do not need to broadcast it to the four winds. When I write, I tend to use a conversational tone and this helps me to bring the hypothetical reader closer to me as if it was a chat more than a lecture. Let the lawyers talk like lawyers. # Typos Seeing typos in written content is almost insulting to the audience these days. With the myriad of AI-powered auto-correction tools, text suggestions, and auto-complete, plus the supply of multiple reliable dictionaries online, a typo gives a strong message of laziness and lack of detail orientation which can be offensive. # Don't Be Ashamed of Reusing Content Eventually, the content you create starts connecting to itself. At some point, you will be able to point your current content to your previous content to augment a point of view, or to elaborate better on a topic. The beauty of content creation is that, at any rate, content starts supporting itself and creates a flywheel effect of sorts. But beware: this does not mean mindless pasting stuff without checking, which nicely sets the floor for the next section. # The Eternal Sunshine of the Document Nobody Will Ever Read We've all been there. Sitting in front of the screen, about to start writing a boring-ass document. Writing can be fun, but there's not much fun in having to write something titled "Software Development Plan Specification" or "Work Package Definition Procedure". In some industries, documents are the principal _produce_ of projects. There is a large number of industries worldwide that are shamelessly document-centric. In these, documents are milestones, main deliverables, and principal subjects of reviews and encumbered meetings. Entire teams fly around the world to gather around a table to discuss a document that is probably 90% pasted from some other similarly ignored document. As boring documents proliferate, content loses center stage and format gains attention. Inverse to what common sense would indicate. Document reviewers start to look more at formatting issues than the content itself. Are the applicable documents correct? Did this person code the document properly? Is the table of contents following the recommended style? At this stage, a document with _lorem ipsum_ would perfectly make its way through the system. In document-centric environments, there are sophisticated document-signing systems that circulate documents around for reviewers and approvers to be able to see the documents and approve them and sign them or reject them. Complex projects can produce hundreds of documents per month, and the strongly hierarchical orientation of these organizations makes it possible for a situation like this to appear: one single person—usually the project's Chief Systems Engineer or similar—being the last single approver of every piece written. It is hard to imagine anything different than this for that poor soul. So, yes, bureaucracy is a thing, but I am not talking about bureaucracy here. What I am talking about is the disregard for accurate, proper, up-to-date content, in favor of mindless pasted stuff put in place only to check boxes or to comply with the reigning status quo. In a company I was working for, there was a set of famous block diagrams that were copied and pasted across a myriad of different documents, even in documents from projects in which the block diagrams were inapplicable because the architecture was different. Still, those block diagrams would be sitting there, and the review chain would be unable to spot the nonsense of having those time and again. Some of these mindlessly written documents are expected to reach X or Y amount of pages to make them "credible" or "good". On one occasion, I was in charge of writing a software user manual for a customer. So, one day I was called for a meeting with a higher-up from my company, who was very interested in knowing the status of this manual because its delivery would unlock a big payment from said customer. In the meeting, this higher-up was not interested in the outline of the doc, or about the content. He asked me straight away: "How many pages do you have?". So, I said, "80". He frowned a bit and said, "Can you make it 115?". "I guess I can". And off I went to inflate the manual with the right dose of filler to achieve the new page goal. Up to this day, I wonder why he said such a precise number. 115. Not a 100 or 120, but 115. Anyway, 115 pages were delivered, the customer was happy, and the money was paid. I am sure no one ever read that document. A sad reality is that a very big portion of these robotically written documents are seldom read. So, why do we keep on writing them? To keep manners? When will someone finally point out the emperor's clothes and say that it makes no sense to spend energy to create documents that no one gives a damn about? More importantly: is there an alternative to the document-centric approach? Well, the solution appears, preliminarily, as worse than the problem. Some claim we are leaning towards a Model-Based era where you would be able to create a model that automatically creates documents. In this way, if you alter the model (because the system has changed its design, or similar) then all documents are automatically updated and exported. Sounds great, but so far, this is mostly pure phantasmagoria. For starters, no one seems to have a solid understanding of what a model is. I see some light at the end of the tunnel where documents in the old-school style are phased out in favor of documents written in markdown which can be more easily parsed and exported to many different formats. # RTFM Say you are tasked with the ginormous challenge of documenting something complex. For example, you are assigned the task of writing a user manual for a big, overengineered piece of software. From the outset, it sounds like a titanic task. Where to start? How to proceed? Well, in a way, it is no different than writing a book. Now, let me tell you a short story about how painful it is to publish a book through an 'established' publishing house. Let's assume you are not J.K Rowling but a John Doe, just like me. So, in general, John Does need to attract book editors, so they are requested to submit book proposals. What are book proposals? They are painfully tedious forms where you need to describe things such as the candidate market of your book, its direct competitors, its potential sales volume, how many color or black-and-white figures you plan to add, and how many footnotes. And the list goes on and on. Then, you must add an outline, some drafts of chapters, the table of contents, and the like. If you pass the first selection criteria---which tends to be hard---then the person handling your proposal will summon a sort of "board of reviewers" composed of some respected people in your field who will go through your proposal and judge it. Mind you, all this can take several months, even years. And then, after an excruciatingly long process, the proposal might be, of course, rejected. Shit happens. If the proposal is approved, you still need to write like 70,000 words in a fairly short time, manage hundreds of figures, and tables, collect permissions, watch copyrights, and whatnot. And all for peanuts or no money at all, because again you are a nobody so the contracts for nobodies can be unfair. But hey, this is the good news I wanted to convey, finally: you do not have to go through that pain with your manual. You are your own publishing house, you decide what to put, and how to put it, and you own the process end-to-end. You get paid for it, and the reviewers are probably way nicer. So, in perspective, writing a user manual for a system is not so bad after all. You can relax and enjoy creating accurate yet entertaining technical material. But, how to proceed? If you have to explain how to operate a complex thing, it is better to put yourself in the right shoes. You might have been a designer or developer of the thing you are now writing about, so you might be prohibitively contaminated by some vices and specifics of the process. You need to get rid of that and think from the customer or operator side. What do they need to know to operate that thing? What are the corner cases? An outline should start materializing from the initial fog. Introduction, some big sections, subsections, etc. A sequence of topics will surely appear, usually following some logical sequence of "from more basic to more advanced". It is important to make sure you state clearly what readers will learn by diving into particular chapters. And, if possible, you should define the chapter logic as "self-contained" as possible. This means readers should not feel lost if they jump one chapter here and there. When writing manuals, it is great to define the outline and then grow the content as evenly as possible. This means, growing in some sort of balanced way the different chapters. It also helps to make the writing process a bit nicer: if you are tired of one section, go somewhere else, start fresh, and later you can come back. It makes little sense to finish a chapter to its fullest when the rest of the manual is still at zero. A manual is a system of sorts, it needs all its parts to mature together to show integrity. One unsaid big drawback of writing is that you have to re-read what you write an unholy number of times. When I wrote that book I wrote, at the end of the process I was truly sick of it. I still am. It can happen, but it still makes sense. As a writer of manuals, the ultimate flattery is a person angrily sending someone to read the fucking manual (RTFM), when said manual is your work. Aim for that.