{"rowid": 57, "title": "Cooking Up Effective Technical Writing", "contents": "Merry Christmas! May your preparations for this festive season of gluttony be shaping up beautifully. By the time you read this I hope you will have ordered your turkey, eaten twice your weight in Roses/Quality Street (let\u2019s not get into that argument), and your Christmas cake has been baked and is now quietly absorbing regular doses of alcohol.\nSome of you may be reading this and scoffing Of course! I\u2019ve also made three batches of mince pies, a seasonal chutney and enough gingerbread men to feed the whole street! while others may be laughing Bake? Oh no, I can\u2019t cook to save my life.\nFor beginners, recipes are the step-by-step instructions that hand-hold us through the cooking process, but even as a seasoned expert you\u2019re likely to refer to a recipe at some point. Recipes tell us what we need, what to do with it, in what order, and what the outcome will be. It\u2019s the documentation behind our ideas, and allows us to take the blueprint for a tasty morsel and to share it with others so they can recreate it. In fact, this is a little like the open source documentation and tutorials that we put out there, similarly aiming to guide other developers through our creations.\nThe \u2018just\u2019ification of documentation\nLately it feels like we\u2019re starting to consider the importance of our words, and the impact they can have on others. Brad Frost warned us of the dangers of \u201cJust\u201d when it comes to offering up solutions to queries:\n\n\u201cJust use this software/platform/toolkit/methodology\u2026\u201d\n\u201cJust\u201d makes me feel like an idiot. \u201cJust\u201d presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. \u201cJust\u201d is a dangerous word.\n\u201cJust\u201d by Brad Frost\n\nI can really empathise with these sentiments. My relationship with code started out as many good web tales do, with good old HTML, CSS and JavaScript. University years involved some time with Perl, PHP, Java and C. In my first job I worked primarily with ColdFusion, a bit of ActionScript, some classic\u00a0 ASP and pinch of Java. I\u2019d do a bit of PHP outside work every now and again. .NET came in, but we never really got on, and eventually I started learning some Ruby, Python and Node. It was a broad set of learnings, and I enjoyed the similarities and differences that came with new languages. I don\u2019t develop day in, day out any more, and my interests and work have evolved over the years, away from full-time development and more into architecture and strategy. But I still make things, and I still enjoy learning.\nI have often found myself bemoaning the lack of tutorials or courses that cater for the middle level \u2013 someone who may be learning a new language, but who has enough programming experience under their belt to not need to revise the concepts of how loops or objects work, and is perfectly adept at googling the syntax for getting a substring. I don\u2019t want snippets out of context; I want an understanding of architectural principles, of the strengths and weaknesses, of the type of applications that work well with the language.\nI\u2019m caught in the place between snoozing off when \u2018Using the Instagram API with Ruby\u2019 hand-holds me through what REST is, and feeling like I\u2019m stupid and need to go back to dev school when I can\u2019t get my environment and dependencies set up, let alone work out how I\u2019m meant to get any code to run.\nIt\u2019s seems I\u2019m not alone with this \u2013 Erin McKean seems to have been here too:\n\n\u201cSome tutorials (especially coding tutorials) like to begin things in media res. Great for a sense of dramatic action, bad for getting to \u201cStep 1\u201d without tears. It can be really discouraging to fire up a fresh terminal window only to be confronted by error message after error message because there were obligatory steps 0.1.0 through 0.9.9 that you didn\u2019t even know about.\u201d\n\u201cTips for Learning What You Don\u2019t Know You Don\u2019t Know\u201d by Erin McKean\n\nI\u2019m sure you\u2019ve been here too. Many tutorials suffer badly from the fabled \u2018how to draw an owl\u2019-itis.\n\nIt\u2019s the kind of feeling you can easily get when sifting through recipes as well as with code. Far from being the simple instructions that let us just follow along, they too can be a minefield. Fall in too low and you may be skipping over an explanation of what simmering is, or set your sights too high and you may get stuck at the point where you\u2019re trying to sous vide a steak using your bathtub and a Ziploc bag.\nDon\u2019t be a turkey, use your loaf!\nMy mum is a great cook in my eyes (aren\u2019t all mums?). I love her handcrafted collection of gathered recipes from over the years, including the one below, which is a great example of how something may make complete sense to the writer, but could be impermeable to a reader.\n\nDepending on your level of baking knowledge, you may ask: What\u2019s SR flour? What\u2019s a tsp? Should I use salted or unsalted butter? Do I use sticks of cinnamon or ground? Why is chopped chocolate better? How do I cream things? How big should the balls be? How well is \u201cwell spaced\u201d? How much leeway do I have for \u201c(ish!!)\u201d? Does the \u201c20\u201d on the other cookie note mean I\u2019ll end up with twenty? At any point, making a wrong call could lead to rubbish cookies, and lead to someone heading down the path of an I can\u2019t cook mentality.\nYou may be able to cook (or follow recipes), but you may not understand the local terms for ingredients, may not be able to acquire something and need to know what kind of substitutes you can use, or may need to actually do some prep before you jump into the main bit.\nHowever, if we look at good examples of recipes, I think there\u2019s a lot we can apply when it comes to technical writing on the web. I\u2019ve written before about the benefit of breaking documentation into small, reusable parts, and this will help us, but we can also take it a bit further. Here are my five top tips for better technical writing.\n1. Structure and standardise your information\nThink of the structure of a recipe. We very often have some common elements and they usually follow roughly the same format. We have standards and conventions that allow us to understand very quickly what a recipe is and how it should be used.\u00a0\n\nGreat recipes help their chefs know what they need to get ready in advance, both in terms of buying ingredients and putting together their kit. They then talk through the process, using appropriate language, and without making assumptions that the person can fill in any gaps for themselves; they explain why things are done the way they are. The best recipes may also suggest how you can take what you\u2019ve done and put your own spin on it. For instance, a good recipe for the simple act of boiling an egg will explain cooking time in relation to your preference for yolk gooiness. There are also different flavour combinations to try, accompaniments, or presentation suggestions.\u00a0\nBy breaking down your technical writing into similar sections, you can help your audience understand the elements they\u2019ll be working with, what they need to do once they have these, and how they can move on from your self-contained illustration.\nTitle\n      \n        Ensure your title is suitably descriptive and representative of the result. Getting Started with Python perhaps isn\u2019t as helpful as Learn Python: General Syntax and Basics.\n      \n    Result\n      \n        Many recipes include a couple of lines as an overview of what you\u2019ll end up with, and many include a photo of the finished dish. With our technical writing we can do the same:\n        In this tutorial we\u2019re going to learn how to set up our development environment, and we\u2019ll then undertake some exercises to explore the general syntax, finishing by building a mini calculator.\n      \n    Ingredients\n      \n        What are the components we\u2019ll be working with, whether in terms of versions, environment, languages or the software packages and libraries you\u2019ll need along the way? Listing these up front gives the reader a great summary of the things they\u2019ll be using, and any gotchas.\n        Being able to provide a small amount of supporting information will also help less experienced users. Ideally, explain briefly what things are and why we\u2019re using it.\n      \n    Prep\n      \n        As we heard from Erin above, not fully understanding the prep needed can be a huge source of frustration. Attempting to run a code snippet without context will often lead to failure when the prerequisites and process aren\u2019t clear. Be sure to include information around any environment set-up, installation or config you\u2019ll need to have done before you start.\nStu Robson\u2019s Simple Sass documentation aims to do this before getting into specifics, although ideally this would also include setting up Sass itself.\n      \n    Instructions\n      \nThe body of the tutorial itself is the whole point of our writing. The next four tips will hopefully make your tutorial much more successful.\n      \n    Variations\n      \n        Like our ingredients section, as important as explaining why we\u2019re using something in this context is, it\u2019s also great to explain alternatives that could be used instead, and the impact of doing so.\n        Perhaps go a step further, explaining ways that people can change what you have done in your tutorial/readme for use in different situations, or to provide further reading around next steps. What happens if they want to change your static array of demo data to use JSON, for instance? By giving some thought to follow-up questions, you can better support your readers.\n        While not in a separate section, the source code for GreenSock\u2019s GSAP JS basics explains:\n        We\u2019ll use a window.onload for simplicity, but typically it is best to use either jQuery\u2019s $(document).ready() or $(window).load() or cross-browser event listeners so that you\u2019re not limited to one.\n        Keep in mind to both:\n        Explain what variations are possible.\n          Explain why certain options may be more desirable than others in different situations.\n        \n    \n2. Small, reusable components\nReusable components are for life, not just for Christmas, and they\u2019re certainly not just for development. If you start to apply the structure above to your writing, you\u2019re probably going to keep coming across the same elements: Do I really have to explain how to install Sass and Node.js again, Sally? The danger with more clarity is that our writing becomes bloated and overly convoluted for advanced readers, those who don\u2019t need to be told how to beat an egg for the hundredth time.\u00a0\nInstead, by making our writing reusable and modular, and by creating smaller, central resources, we can provide context and extra detail where needed without diluting our core message. These could be references we create, or those already created well by others.\n\nThis recipe for katsudon makes use of this concept. Rather than explaining how to make tonkatsu or dashi stock, these each have their own page. Once familiar, more advanced readers will likely skip over the instructions for the component parts.\n\n3. Provide context to aid accessibility\nHere I\u2019m talking about accessibility in the broadest sense. Small, isolated snippets can be frustrating to those who don\u2019t fully understand the wider context of how our examples work.\nShowing an exciting standalone JavaScript function is great, but giving someone the full picture of how and when this is called, and how it should be included in relation to other HTML and CSS is even better. Giving your readers the ability to view a big picture version, and ideally the ability to download a full version of the source, will help to reduce some of the frustrations of trying to get your component to work in their set-up.\u00a0\n4. Be your own tech editor\nA good editor can be invaluable to your work, and wherever possible I\u2019d recommend that you try to get a neutral party to read over your writing. This may not always be possible, though, and you may need to rely on yourself to cast a critical eye over your work.\nThere are many tips out there around general editing, including printing out your work onto paper, or changing the font size: both will force your eyes to review it in a new light. Beyond this, I\u2019d like to encourage you to think about the following:\n\nExplain what things are. For example, instead of referencing Grunt, in the first instance perhaps reference \u201cGrunt (a JavaScript task runner that minimises repetitive activities through automation).\u201d\nExplain how you get things, even if this is a link to official installers and documentation. Don\u2019t leave your readers having to search.\nWhy are you using this approach/technology over other options?\nWhat happens if I use something else? What depends on this?\nAvoid exclusionary lingo or acronyms.\n\nAirbnb\u2019s JavaScript Style Guide includes useful pointers around their reasoning:\n\nUse computed property names when creating objects with dynamic property names.\nWhy? They allow you to define all the properties of an object in one place.\n\nThe language we use often makes assumptions, as we saw with \u201cjust\u201d. An article titled \u201cES6 for Beginners\u201d is hugely ambiguous: is this truly for beginner coders, or actually for people who have a good pre-existing understanding of JavaScript but are new to these features? Review your writing with different types of readers in mind. How might you confuse or mislead them? How can you better answer their questions?\nThis doesn\u2019t necessarily mean supporting everyone \u2013 your audience may need to have advanced skills \u2013 but even if you\u2019re providing low-level, deep-dive, reference material, trying not to make assumptions or take shortcuts will hopefully lead to better, clearer writing.\n5. A picture is worth a thousand words\u2026\n\u2026or even better: use a thousand pictures, stitched together into a quick video or animated GIF. People learn in different ways. Just as recipes often provide visual references or a video to work along with, providing your technical information with alternative demonstrations can really help get your point across. Your audience will be able to see exactly what you\u2019re doing, what they should expect as interaction responses, and what the process looks like at different points.\nThere are many, many options for recording your screen, including QuickTime Player on Mac OS X (File \u2192 New Screen Recording), GifGrabber, or Giffing Tool on Windows.\nPaul Swain, a UX designer, uses GIFs to provide additional context within his documentation, improving communication:\n\n\u201cMy colleagues (from across the organisation) love animated GIFs. Any time an interaction is referenced, it\u2019s accompanied by a GIF and a shared understanding of what\u2019s being designed. The humble GIF is worth so much more than a thousand words; and it\u2019s great for cats.\u201d\nPaul Swain\n\n\nNext time you\u2019re cooking up some instructions for readers, think back to what we can learn from recipes to help make your writing as accessible as possible. Use structure, provide reusable bitesize morsels, give some context, edit wisely, and don\u2019t scrimp on the GIFs. And above all, have a great Christmas!", "year": "2015", "author": "Sally Jenkinson", "author_slug": "sallyjenkinson", "published": "2015-12-18T00:00:00+00:00", "url": "https://24ways.org/2015/cooking-up-effective-technical-writing/", "topic": "content"}