Author Archives: Sarah Maddox

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.

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. 🙂

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. Tech Comm on a Map is available as a native Android app as well as a webapp.
  • The information sources that I used when developing the app.

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

  • My engineering colleagues helped me 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.

Here’s the session on the STC Summit schedule: A tech writer, a map, and an app.

You can also read more about the app, Tech Comm on a Map.

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.

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.

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.

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:

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!

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.)

%d bloggers like this: