Author Archives: Sarah Maddox

How to write a presentation

I’ve just finished writing a presentation for the upcoming STC Summit 2017. Putting together the slide deck and notes made me ponder on how I go about creating a presentation, and to wonder whether other people follow a similar path.

This post is about the process of developing a presentation, rather than what to put into it. Here’s how I prepare a presentation.

Grab the idea when it floats by

  • Make a note of any ideas for a presentation, and keep the list somewhere handy. Some ideas sit around for months or years before a good occasion comes along.  I use an online document for my list of ideas, so I can add to them no matter where I am when an idea occurs.
  • Think up a title for the presentation. It’s often best to think up one or more names while the idea is still fresh. The title captures the original intention and mood of the idea.

Submit a proposal to speak at a specific event

  • Keep an eye out for a conference or other occasion where my idea will fit in. Conferences often have a theme. For example, the theme of the STC Summit 2017 is Gain the Edge to Get Results. Every conference has a target audience. It’s important to submit a proposal that suits the theme and audience.
  • Think about the title again. Sometimes I need to change it, to suit the event and audience.
  • Write an outline of the presentation, bearing the audience and theme in mind. Some conference committees want a full outline, others ask for a summary of what the attendees will learn from the presentation. This step takes a lot of time, because it determines the final content of the presentation. Usually, though, I find it reasonably easy to create the outline, because I’m keen on the theme of the presentation. It’s something I’ve been wanting to talk about for a while. I think about the audience continually: What do they want to learn from this session, and what can I promise to show them. Everything that I put in the outline must be achievable and reflected in the eventual presentation.
  • Write a session summary. This is more of a “blurb”, an inspirational invitation to people to attend the talk. It needs to contain factual details of what’s in the session, and it must also reflect my passion about the topic.
  • Submit the proposal, along with other information requested by the conference committee. This may include a bio, a headshot, audio-visual requirements, and so on.

Prepare the presentation

  • Grab more ideas as they drift by. At this stage, my brain is actively engaged in the presentation, and ideas pop up at all sorts of times. Don’t let them get away!
  • Extend the outline. Still working in a doc rather than a slide deck, I add the notes from those drifting ideas. I copy and paste stuff from everywhere. Often I don’t try to make the notes tidy. They don’t even need to fit in completely. The outline is at the moment just a collection of potentially useful facts, quirks, quotations, ideas for illustrations, laughs, and what have you. It gets messy, but that’s OK. Until it’s not OK.
  • Get visual. At some stage, notes become boring, messy, and counter-productive. For me, the visual aspect of the presentation is as important as the content. The structure conveys the theme. The colours make the audience (and me) restive or restful. Images convey meaning or complement the content. The presentation starts to fly when I move it from a doc into slides.
  • Create the presentation outline and section headings that the audience will see. I think it’s useful, and kind 🙂 to give the audience an outline at the start, and show them header slides for each section with an indication of the section’s place in the presentation as a whole. This helps the attendees organise the information in their own heads. It also gives them a feeling of progression. We’re not lost in a spiral of slides. We have a destination and we’re getting there. It’s also fun to have a visual theme for the header slides – a way of presenting progress that fits the theme of the talk. I’m ready to change the outline, and thus the sections, as I develop the content. Change is inevitable and inexorable.
  • Write the slides and first draft of speaker’s notes, at the same time. Some slides are purely visual, others are bullet points. The speaker’s notes help me decide what each slide is about.
  • Keep going with content development, but be ready to jump back and adjust previous slides. Most times I find myself shuffling things around, from slide to slide, and even moving chunks of slides further up or down the flHow to write a presentationow.
  • Recognise and bypass deadlocks. If I get stuck while developing the content, I go for a walk. Often I’m stuck because I don’t want to change something. I really, really don’t. Or perhaps I don’t even recognise that the change is necessary. But there’s no easy way forward without the change. So, I go for a walk. I don’t consciously think about the problem, but I’m open to suggestions from my subconscious. If an idea pops up, I note it down right then and there. I send myself an email, or scribble a note on a scrap of paper. In my experience, it’s best to make those notes immediately, before my presentation-weary, brain-washed self has a chance to tamper with the wording. The words of the thought that popped up encapsulate the insight that my subconscious is offering.
  • Ask for a review. When the first draft is ready, I ask for a friendly review from a colleague, or from someone who matches the intended audience of the talk. People often have really great feedback, ranging from things like, “the aspect ratio is wrong in that image”, to, “it’d be good to add a bit about what went wrong”.

Prepare to present the talk

  • Set aside a number of one-hour sessions. This part of the preparation takes a long time. It’s also quite tiring, so I need to spread the sessions over a number of days.
  • Find a quiet room.
  • Talk through the slides. Start at the very beginning, and speak out loud.
  • Refine the speaker’s notes as I go. I prefer to present without notes, so for me the speaker’s notes are a handy place to note the things I want to say, when creating the presentation, rather than an aid during the talk itself. The notes are also useful for the reviewers, and perhaps for other people who read the slide deck later without the benefit of seeing it presented.
  • Be prepared to change the slides even at this late stage. When I talk myself through the deck, I see how it’ll work in front of an audience. Sometimes things don’t work as I expected.
  • Time the presentation. When I’m happy with the slides and notes, I talk through the slides from beginning to end, still reading from the notes but without stopping to adjust the notes or slides. If there are any demos, I do those too. I note the start time and end time, and thus the length of the talk. This is the best way to ensure the talk will fill but not exceed the session time.
  • Hide the speaker’s notes. Of course, I can’t do this all at once, as it’s hard to remember all that content. Instead, I kind of look at the notes out of the corner of my eye when I need them, and try to present as much as possible without them. At this stage, it’s not important to repeat the content of the notes word for word. It’s good to fly free of the notes, provided I’m sure I include everything that I intended to include.  I do this a few times, until I can hide the notes entirely.
  • Make a PDF version of the slides. I prefer presenting from PDF rather than a browser, because it’s easy to flip between a PDF document and a demo in the browser. I find that I can use the full-screen PDF mode without losing the easy navigation to the browser or other apps on the computer.

A tip about overcoming stage fright

A by-the-way hint just occurred to me while finishing off this post. It’s the most useful thing anyone ever said to me, about how to overcome stage fright. Take a step forward as you start to speak. I used to skulk behind the speaker’s podium, shivering and stiff with nerves, and basically stay that way throughout my presentation. I still get very nervous, but following the advice to step forward really helps. Moving my body kind of frees me from that initial blue funk. It gives the audience the feeling that I’m speaking directly to them. If I need to, it’s fine to go back behind the podium later, such as when I need to give a demo or press the button to advance the slides.

That’s it. 🙂 Looking at these notes, I see that it’s a lot of work. But I think it’s worth it. Attending a conference is a privilege and a pleasure, and speaking at one is even more so. What do you think, and do you follow a similar process when creating a presentation? If anyone has any tips to help aspiring presenters, those’d be most welcome.

What do you want to know about Tech Comm on a Map?

I’m putting together a presentation about Tech Comm on a Map, the app that shows technical communication events and groups around the world. What would you like to know about the web app and the Android app for Tech Comm on a Map?

It’s a little scary for a tech writer to create and publish an app. Actually, it’s a little scary for anyone. Are you curious about any particular aspects of why I did it, what the results are, or anything else? If I can, I’ll weave the answers into the presentation.

Tech Comm On A Map

I’ll be speaking about Tech Comm on a Map at STC Summit 2017 in May, and possibly at other events after that. At the moment, I’m writing the presentation based on my early proposal and outline. I’m having fun! But before I get too invested in what I think is fun, I’d love to hear what other people think too.

The theme for STC Summit 2017 is “Gain the Edge to Get Results“.

Here’s the blurb and outline from the proposal I sent to the STC Summit committee.

Blurb

As an API technical writer, it’s hard to put yourself in the shoes of your readers. They’re application developers. They’d rather read code than prose.

Tech Comm on a Map for AndroidOne way of grokking this audience is to develop an app yourself.

This presentation tells the story of a tech writer, a map, and an app. The app is Tech Comm on a Map, an interactive web-based map that shows events of interest to technical communicators. You’ll hear why Sarah decided to create an app and how she went about it. You’ll see some code and understand the nuts and bolts of the app: where the data is stored, how it gets there, how it ends up on a map for everyone to see.

Tech Comm on a Map is an app for technical communicators, and technical communicators contribute to the data. Sarah will describe the process of crowd-sourcing the data and open-sourcing the app: what went well, what went slowly, what’s still going.

Writing an app has helped Sarah understand her audience (software engineers), her subject matter (APIs), and her profession (technical communication). Come and see how.

Outline

It’s hard to create an app. It’s even harder to get the app published and make it available to other people. That’s true whether you’re a developer or a technical writer. You need to put yourself on the edge and take the jump. You need courage, strength of conviction, and knowledge. Above all, you need documentation and examples. They give you the edge.

By taking the jump into app development, Sarah has gained first-hand knowledge of what developers go through. She applies this knowledge to the documentation she writes. It’s also a lot of fun!

At this session, you’ll learn the technical details:

  • The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
  • How the app’s data is crowd-sourced.
  • What open sourcing your code means, and why you may want to do it.
  • The difference between a web-based application and a mobile app, from a developer’s as well as a user’s point of view. Tech Comm on a Map is available as a native Android app as well as a webapp.
  • The information sources that Sarah used when developing the app.

You’ll also see how such a project can help develop your soft skills:

  • Sarah’s engineering colleagues helped her kick off the development of the app, and made ongoing suggestions for refinement. The resulting interactions increased mutual understanding and respect.
  • Fellow technical writers all over the world help compile the data. A project like this is a good way of connecting with your peers.
  • Developing an app can help you better understand your subject and your audience of software engineers and other specialists.
  • Such a project gives you confidence in your own abilities, even if you’re just skimming the surface of code complexity.

See Tech Comm on a Map in action at https://sarahmaddox.github.io/techcomm-map.

What are you curious about?

Does the above description raise any specific questions in your mind? Is there something you’re very keen to find out? Let me know, and I’ll include it in the presentation if I can.

Sarah’s hevvy fruitcake

It’s that fruitcake time of year. I made one that was a bit of an experiment and it worked rather well. What’s more, it’s gluten free. Here’s the recipe, for those adventurous souls who want to try it.

Sarah's hevvy fruitcakeNote: Baking is an imprecise art, and so is this recipe. It’s a little like technical writing. 😉 Oh, and the spelling of “hevvy” is intentional.

Oven temperature: 180° C (360° F).

Baking time: 60 minutes.

Baking pan: Round. Diameter 23 cm (10 inches), height 6 cm (2.5 inches).

Baking paper to line the pan.

Ingredients

Cake:

  • 225 g (8 oz) brown sugar – the darker the better. I used dark muscovado unrefined cane sugar.
  • 225 g (8 oz) margerine or butter – I used margerine.
  • 4 eggs.
  • 400 g (12 oz) cake flour – I used gluten free flour.
  • 1 teaspoon nutmeg.
  • 1 teaspoon cinnamon.
  • Half a teaspoon mixed spices.
  • Pinch of salt.
  • 200 g (7 oz) sultanas.
  • 200 g (7 oz) blackberries or some other squishy, slightly sour berry – I used frozen blackberries.
  • 2 handfuls pecan nuts – basically, as many as you want.
  • 1 teaspoon vanilla essence.
  • 50 ml (2 tablespoons) molasses.
  • 50 ml (2 tablespoons) or more plain yoghurt (if necessary, make sure it’s gluten free).

Topping:

  • 6 tablespoons brown sugar – but have more available, because the topping is tricky.
  • 50 ml water.

Method

A slice of hevvy fruitcake looks like this:

hevvy-cake-slice

Cake

Mix the margerine/butter and sugar. Add the eggs one at a time, mixing each egg in well.

Add the flour, nutmeg, cinnamon, mixed spices and salt. Here’s a tip to prevent flour from flying everywhere: Use a wooden spoon to mix the dry ingredients at first, then use an electric mixer to finish the job.

Chop the pecan nuts into largish pieces – quarters or thirds of a nut are good.

If you’ve been using an electric mixer, now’s a good time to abandon it.

Add the sultanas, blackberries, and chopped nuts to your mixture. Also add the vanilla essence, molasses and yoghurt.

Mix it all together with a wooden spoon. Don’t worry about getting everything 100% mixed in. It’s fine if there are still a few visible globs of yoghurt when you’ve finished.

Baking

Line the baking pan with baking paper. Spoon the mix into the pan, ensuring a more or less level surface. Bake for approximately an hour at 180° C (360° F).

Stick a thin knife into the cake to check it after about 40 minutes, and then again every 15 minutes or so, to see how it’s doing. When you pull out the knife, the blade shouldn’t be completely clean (it’s better if the cake is moist). It should have some moist, slightly gooey stuff on it, but not a lot of uncooked dough.

Remove the cake from the pan and put it on a metal rack to cool. Leave the baking paper on the cake until it’s cool.

Topping of caramelised sugar

The aim here is to heat the sugar and water until the sugar caramelises, then pour it onto the cake before it sets hard.

Set a pot of cool water ready, for testing your caramel mixture. (Cold water from the tap is fine.)

Put the sugar and water into a small saucepan and bring to the boil on a high heat, stirring continuously with a wooden spoon. At first, the sugar mixture is thin with lots of small bubbles. Keep it boiling and keep stirring. The sugar mixture gets thicker and darker.

Now it’s time to test the mixture. Take your wooden spoon out of the pot and hold it over your separate pot of cool water. Let a drop of the sugar mixture fall into the water. Prod the drop with your finger – it should be hard to the touch. If it’s still squishy, or if it disperses and flattens when you drop it into the water, then the caramel mixture isn’t yet ready.

When ready, dribble the caramel mixture over the top of the cake. Don’t worry if it’s not evenly spread – there’s no need to cover the whole cake, and it’s fine to have deep and shallow valleys of sugar.

Here’s another tip:  If the sugar crystalises in the pan, it’s not hard to wash, despite the scary appearance of the caramel-encrusted pan. This means you can quickly start again with another mixture of sugar and water if things go wrong the first time.

Enjoy the cake!

Modern technical writing, a talk by Andrew Etter about his book

Yesterday I attended a Write the Docs meetup where Andrew Etter spoke about his recently published book, Modern Technical Writing: An Introduction to Software Documentation.

I haven’t read Andrew’s book yet, so I appreciated this introduction from the author. One thing that strikes me is how interwoven are two aspects of technical writing: firstly, the processes (the way we glean our material and our efficiency and efficacy in writing content); secondly, the tools we use. Every now and then, I’ve heard people say we shouldn’t focus so much on the tools when discussing our profession and how best to perform our role. I’ve thought that too, at times. But it seems to me that these two aspects of our work are becoming more and more interdependent. The tools make a specific way of working possible, and the way we think of our work determines the tools we choose.

From what Andrew said about his book yesterday, the content of the book seems to agree with my above musings. Now, I should go and read that book. 🙂

Modern Technical Writing, the book

Andrew pointed out that you can read his book in about 45 minutes, and that he’s been allotted an hour for this talk! This comment raised a good laugh.

The book is about 11,000 words. Andrew summed it up (with a smile) in about 12 words, which roughly correspond to the highlighted words in the list below:

  • Learn – learn your subject matter and get to know your audience.
  • Write in lightweight markup – it’s the easiest way to get from a pleasant writing experience to a useful website. Markdown is a good solution, because people want to use it. You’ll therefore have plenty of people willing to contribute to your docs.
  • Treat the docs as code – version control and continuous updates. The stability of the docs over time depends on the quality of your updates.
  • Create static websites.

The book, Modern Technical Writing, started as a wiki page. Andrew needed information about technical writing to pass on to others. He did a bit of research, to see if anything already existed that he could use. Having found nothing that fit the bill, he decided “I’m the writer”, and wrote it himself.

What makes a book sell?

Andrew spoke amusingly about an FAQ on the Kindle Direct Publishing site: “Why am I not selling? I am a good writer.” The fundamental question is, how do you get people to buy something you’re selling? Andrew said with a smile that he has no idea! He doesn’t do much marketing or promotion via social media. Here’s his recommendation:

If you have something you feel strongly about, something you’ve shown to your friends and got good feedback on, something you think adds value to the world, then put it out there.

The publishing process

Andrew chose Kindle Direct Publishing as the mechanism for publishing and earning royalties. The rules around pricing are really complicated. The magic happens when you upload your book to Amazon, and they transform it to a Kindle book. Amazon is the market leader in online publication, and your book benefits from this.

One drawback is that you cannot test your book before publication. You just upload it, view the highly inaccurate preview, and then publish it.

The aftermath

Andrew showed us a screenshot of his book on Amazon right next to Strunk and White’s Elements of Style. To be near Elements of Style is mind-boggling. But it lasted a very short time. He  dispelled any myths that self-publishing is lucrative. He has, however, received very nice messages from people all over the world.

Charging a price for the book

If you give something away for free, there’s the perception that it’s not really valuable. If you give it a price, people are more likely to see it as worth something.

For his book, Andrew thinks that the price of around $4 is in the right range.

What technical writers do

What is the “differentiated value add” of a technical writer? That is, what do we do that no-one else does?

  • Consistency – specifically, consistency in tooling. Without tech writers, each engineering team would pick their own tools, which would result in chaos.
  • Accountability – someone has to be responsible for creating good documentation. Andrew remarked with a smile that you have to be able to fire someone if the documentation is bad.
  • Creation and curation – writers review and take care of others’ content as well as writing it.
  • Culture – having good writers around makes everyone else aware of what good writing looks like.
  • Good documentation leads to efficiency improvements in many ways. It helps the organisation and customers save time, and time is a precious resource.

Andrew talked a bit about the writing process, project prioritisation, and the team. He joked at the beginning of the presentation that these topics may form part of the second edition of the book, if he ever considers writing one.

The old way versus the new way of producing documentation

Andrew talked about old methodologies and tools versus the new ones, and walked through some code samples. I didn’t make notes of this part of the talk. The details are in Andrew’s book.

Conclusion

Thanks to Andrew Etter for an engaging presentation and congrats on your successful book!

Where do technical writers fit in an organisation

Where do technical writers belong in an organisation? Which team should we be part of? This is an interesting question that many of us are asking. I don’t have an answer. In fact, there are probably as many answers as there are possibilities, because each organisation is different, and so is each technical writing role. But I do have some musings and two presentations to introduce.

Where we end up in the organisation can affect the way other people see us and our contribution to the company. It can affect our own perception of our purpose and goals. It may even affect our ability to do our job, if our position in the company determines the access we have to information, technology, and other resources.

Sometimes, we’re lucky enough to have a say in where we end up. That’s when it becomes really interesting, because the choice may not be easy.

Where do we belong?

Here are some of the possibilities:

  • Engineering and product management: Technical writers work closely with the software developers to understand the ins and outs of the product. It’s also very useful if technical writers can give early input into the design of a product, taking advantage of the user-focused nature of a technical writer’s role.
  • User experience: Technical writers, UX designers and UX researchers are focused on the needs of the customer. They often work closely together in producing the documentation and other user aids, even if they’re not part of the same team.
  • Support: The documentation is an essential resource for the support team. Working as part of support can give technical writers direct access to the requests and problems reported by customers.
  • Marketing: The documentation is an important marketing asset, and the level of technical detail in the documentation tends to yield excellent SEO (search engine optimisation). Technical writers and marketers often find themselves writing about the same products and topics, especially at the launch of a new product or feature. Marketing teams have great resources for customer analysis, and a flair for words.
  • Developer relations: This is a team of people with various roles, including technical writers, software engineers, developer advocates, marketing leads, and others. The team acts as an interface between the internal teams who’re developing the products, and external developers/customers who’re using the products. The products are developer-focused, including APIs, SDKs, libraries, and so on.
  • Change management: See the comments on this post for discussion.
  • Any more?

Two takes on working with product teams

Recently I presented a webinar on working with an engineering team, and I attended a talk by Craig Simms on integrating more closely with a product team. It’s interesting to compare these two takes on the topic.

Webinar: Working with an Engineering Team

The ASTC (Australian Society for Technical Communication) and I recently collaborated to host a webinar on working with an engineering team. You can watch the recording below, and on Vimeo. The slides are available on SlideShare.

Click the play button to view the video above.

Talk: Integrating with Software Product Teams

At a recent Write the Docs meeting, Craig Simms presented a talk on how technical writers can integrate more closely with software teams. It’s a zestful account of the journey he and his colleague have taken towards becoming integrated with a product team, and the lessons learned during that journey. The recording is on YouTube, and embedded below.

What do you think?

Where do technical writers fit in, and do you know of any other presentations that talk about integrating with various teams?

%d bloggers like this: