Sarah Maddox's Blog, page 14

Talking about APIs and Maps at STC Summit 2017

I’m excited to be speaking soon at STC Summit 2017, the annual conference of the Society for Technical Communication. The event happens in Washington, DC, on 7-10 May. My presentation is about APIs, maps, developers, and a tech writer’s foray into the world of app development.

The conference theme is “gaining the edge”. So I decided to talk about my experiences developing an app, and why I tried my hand at app development. The app, Tech Comm on a Map, is an interactive web-based map that shows events of interest to technical communicators.

In this presentation, 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.

Follow me on a tech writer’s odyssey into app development.

Tread in dangerous territory.

We may even see a dragon or two.

Emerge a little triumphant, and certainly well travelled.

[image error]

Q: Why does the journey on this map start in Sydney and end up on the east coast of the US?

A: Because that’s the trip I’ll make to give this presentation at STC Summit.

Simple goals for information architecture

Information architecture (IA) is a complex subject. The term IA can encompass a wide variety of design considerations and methodologies. I’ve recently run an IA project that focuses on a few aspects of our documentation site, so I decided a post about it may be interesting. I’m hoping the post may help people to wrap their minds around IA before getting into the nitty gritty of such a large topic.

In essence, the focus of our recent information architecture project was to help readers find the information they need. We focused on developers, because they form a significant part of our audience. We looked at three user flows:

Entering at the top of the site, looking to explore the products.
Entering the site on a page that’s deep in the information hierarchy, coming from a web search or external link and looking for a specific answer.
Using the information on a given page.

I’m using the term “top of the site” to mean the conceptual, introductory pages that usually occur first in a navigational structure.

Readers entering from the top of the site

Some readers enter the site in exploratory mode. By that I mean they’re looking for an overview of the product or products, and want to be led through the concepts in a logical flow.

The destinations of your links depend on your analysis of where your readers want to go. For example, user research may show that people want to see a product overview followed by a getting-started guide. Your organisation may also want to help people find a summary of support options or contact the sales team.

[image error]

Readers entering the site on a specific page deep in the information hierarchy

Many readers enter a site via searching on the web, or by a link that someone else has supplied in a forum or a help article. These readers start their experience of your site on a page that’s deep in your hierarchy of information. They may find the answer to their specific question on the first page they land on, but then they probably want to learn more about the product or tool. Or perhaps they don’t find the answer on the first page they encounter, and they want to look further.

[image error]

In this case, the navigational elements on and around the page are very important. People need context, to figure out where they are and how they can move around the site to get more information. Here’s a good way to think about it: Every Page is Page One.

Readers getting information from a given page

The structure of a page is an important part of information architecture too. The page needs to provide context, perhaps simply in the form of the navigation aids discussed above. The page may also need to cater for readers who already have a good technical knowledge, and just need a quick orientation of where and how to do something. Other readers may need a detailed step-by-step guide.

[image error]

In the case of API documentation or other developer-focused docs, the quick guide may be just a code sample, as we discovered in our recent user studies. There’s some information in my post about the Google Maps APIs tutorials.

More about IA

That was a quick introduction to some concepts of information architecture. Here’s more detail from various sites:

Usability.gov
Information Architecture Institute
UX Booth
Wikipedia

Tech writing and IA

Do you have any experiences to share about technical writing and information architecture, perhaps from a different angle that what I’ve described? I’d love to hear about your experiences too!

Report from Write the Docs Sydney, March meetup

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.

Designing tutorials – some insights for API documentation

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?

Today’s laugh from a tech writer who reviews a lot of code

I just sent an email message to a colleague, which looked something like this

Hallo Sally

Yes, please do send me those docs for review.

Have a great Monday!

Cheers

Sarah

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.

Report from first Write the Docs Brisbane meetup

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.

[image error]

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.

The tools:

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.

[image error]Customer proxies are people and systems that you can use to represent your audience. These are people or systems who have a closer relationship with your customers than you do.

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.

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.

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

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.

[image error]

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.

[image error]One 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.

[image error]Note: Baking is an imprecise art, and so is this recipe. It’s a little like technical writing.

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.