We held the second Write the Docs meetup in Sydney on 2 March. The presentations were on moving into API technical writing, and the story of the Corilla documentation platform.
There was a good crowd at this meetup – around 20 technical writers descended on the Campaign Monitor offices in central Sydney. We were treated to a breath-taking 360-degree panorama of Sydney from the 38th floor of the building, and a couple of entertaining, informative, very different talks.
The recording of the session includes both talks, and is available on YouTube:
Presentation 1: Transitioning into API Tech Writing
The first presentation was from Priya Varghese, a technical writer at Google. Her talk was titled Transitioning into API Tech Writing. A year ago, Priya started work at Google as an API technical writer. Before that, she had many years’ experience as a tech writer for other audiences in the medical, security and education industries.
Priya talked about the questions she had before embarking on this new role, such as: How different is it from tech writing for other audiences? Do I know enough to explain APIs to developers? What if I don’t know how to code? Can API tech writing be fun? Her presentation gives an overview of APIs and the developer audience, the role of an API tech writer, the things you need to know, and the skills you need to acquire. One thing Priya strongly recommends is a mentor, and she finishes her talk by wondering if we should develop mentorship programs to guide and instruct technical writers.
Presentation 2: The Corilla Story
David Ryan, co-founder of Corilla, told the story of the development of Corilla and the forming of a startup. Corilla is an online documentation platform for technical writers, providing documentation authoring, publication and version-control tools. David’s talk was fun and educational, with intriguing glimpses of the roller-coaster ride of a startup founder.
David described how he and his team had the original idea for a new tool while working with a set of tools that was bloated, clumsy, and not designed for technical writing. Their new tool quickly became popular at Red Hat, where David was working at the time. With Red Hat’s blessing, he and his colleague branched out to form their own startup. And the rest is history. Two years later, Corilla is an alumni of the NUMA accelerator in Paris and has customers in more than 80 countries. Watch the video to hear David talk about the journey from then to now.
I’ve just published a blog post on the Google Geo Developers Blog, about a new design for the Google Maps API tutorials. I’d love some feedback from technical writers. If you have a few minutes, would you head on over there and let us know what you think?
I just sent an email message to a colleague, which looked something like this
Yes, please do send me those docs for review.
Have a great Monday!
My brain told me I should indent lines 2 and 3 in the above message. That made me laugh, because I think the reason my brain said “indent, indent”, was that I’ve been reviewing a lot of code recently and indentation is key for code readability. On the other hand, I could be harking back to the indented style of letter writing. Or perhaps I should add more spacing between the lines…
How to over-analyse a simple message. 🙂
(In the above sample, I’ve changed the name of my colleague and the content of the first line.)
Today I attended the first ever Write the Docs meetup in Brisbane. It’s the third in the super-popular Write the Docs Australia series.
We started by going round the room introducing ourselves and describing the document we’re most proud of. Stories ranged from blogs, books, and job ads, to documents that actually contained the word “blah blah blah” before given tech writer luv.
There were 3 presentations at this bumper session:
- From Hackathon to Help System, by Jared Morgan
- No-contact Customers: Customer proxies and how to use them, by Laura Bailey
- Writing clearly: a super-power for software developers, by Josh Wulf
From Hackathon to Help System
Jared Morgan gave an amusing and information-packed account of how he implemented an open-source help solution for a product that wasn’t originally designed to support embedded help. He talked us through the original idea for an open-source help product, which he worked on with a partner. The system was to be written in AsciiDoc. The plan was to render the help on hover, using asciidoctor.js.
Jared and his partner didn’t get around to implementing that solution, but an opportunity came up to use the idea at Ladbrokes, where Jared currently works. He initiated the project during a hackathon: putting embedded help into an existing system. There were a number of challenges, because the system wasn’t designed with user assistance in mind. For example, there was no easy way to uniquely identify the fields.
Jared introduced us to a new term: DragonForce a solution. The term comes from a heavy metal band that’s enthusiastic but not particularly methodical in approach. The basic idea was to render the help content when the user clicked a help button. They also wanted to use open source technology, and to use single sourcing of the content.
- Asciidoctor for source content
- Middleman as static site builder
- Franklin as static site framework
- GitLab for on premises hosting
Then came the serious task of releasing the product to real customers. Jared told us how the system needed to be refined and go through QA to prepare it for release. And he gave some pointers into things he’d do otherwise on hindsight.
Jared’s take-aways from the project.
- Developers do care about docs.
- DevOps teams to get things done, and are worth getting to know.
- It’s good to get outside your comfort zone, and learn the challenges the developers have.
- You can think outside the box, and not let your department define the scope of your role as tech writer.
No-contact Customers: Customer proxies and how to use them
Laura Bailey talked about no-contact customers – that is, people you can’t get in touch with. Technical writers need to know their audience. But as businesses grow, customers tend to get further away. So what can you do when you have a no- or low-contact audience? Laura talked about how to be your own data scientist.
Examples of people who may be customer proxies are sales staff, consultants, developers, data scientists. On the systems side, there are support requests, comments, forums, site metrics, surveys, and so on. You need to analyse your own organisation to find out which apply. Laura mentioned that you can even search the Internet for complaints and reviews of your product from customers.
Once you have the data, you need to process it to make it useful. Scrub it and structure it. You may need to do this manually, if you’re listening to phone call recordings, for example. Or automate the scrubbing if you can work with log output, for example.
A hint from Laura is to think of the future, when analysing and recording the data. Think about aspects of the data that you may need to use in future, and record the relevant data points now. It’s also worth noting that often you’re working with systems that are designed for teams other than tech writers, such as sales staff. So think carefully about which data points can provide insights into the questions you have.
Scrutinise your data, and bear in mind where it came from. Avoid confirmation bias. Find as many data sources as possible, and try to support your conclusions with data from more than one source.
It’s a lot of work, says Laura. Data and its analysis is one of the biggest problems in the tech industry, and is currently a focus too. So take care to target your workload to the questions you need answered. Use the work to proactively prevent growth of the problems you’ve targeted.
Writing clearly: a super-power for software developers
Josh Wulf gave a rollercoaster talk about his experiences in developing Magikcraft.io, which teaches children to code in Minecraft. My summation: Trillions of GitHub commits, oodles of smart people, crazy love of code.
Josh invited us to observe 10 seconds of silence for all of the unread docs. 🙂 And he played us some Roger Troutman.
Some nuggets from Josh: Sometimes we think that language just describes things, but language actually creates the world. It gives us the ability to observe our own actions. At first you’re unconscious of your actions. But then you write it down, and you can analyse it. Bug reports are a good example. Diagrams do the same thing.
A good way of helping people is to ask them to tell you, and to tell themselves:
- What I did.
- What it did.
That’s often enough to solve the problem.
It’s a wrap
Thanks to Swapnil Ogale and all the Write the Docs attendees for another great meetup!
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 flow.
- 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.