Blog Archives

Add 2016/17 events to the map

tech-comm-map-screenshot_2016-08-22Tech Comm on a Map is ready for 2017! I’ve added a category for “Conferences 2017” and styled it a cool grey. (Grey is THE colour for 2017, right?)  The map already has a few events scheduled in 2017. If you know of any more, it’d be great if you’d add them.

Tech Comm on a Map (available on the web and as an Android app) puts technical communication titbits onto an interactive map.

Add events, groups, societies, businesses and more

The data on the map is crowd sourced. If you know of an event, a business, or something else related to tech comm, please add it. You can use this online form, or you can use the Android app (see below).

See the map on the web

See Tech Comm on a Map in action in your browser. Plot tech comm events and organisations around the world. You can even embed the map into your own web page. See the details.

Grab the Android app

Tech Comm on a Map (Android) is available as an Android app.

Get it on Google Play

First Write the Docs in Australia

The first Write the Docs meetup in Australia is happening soon! I’ll be there, to lead a discussion around working with engineers. Huge thanks to Swapnil Ogale for organising this first meetup ever in Australia.

The session will be in Melbourne at 6pm on Friday, 9 September 2016. Can you come? For more session details and signup, see the Write the Docs Melbourne meetup.

About Write the Docs

Write the Docs (WtD) is an informal community of people interested in technical documentation: technical writers, engineers, UX designers, support engineers, editors, and more. The heart of the community is a series of meetups that happen in various parts of the world. There are also a few annual conferences.

You don’t need to belong to any organisation. Just register for a meetup in your area of the world.

Topic for the Melbourne meetup: Working with Engineers

Swapnil Ogale is the organiser of the Melbourne WtD meetup. He’s invited me to lead the discussion at this first session. We’ll talk about working with engineers. I’ll start with a presentation (about 20 minutes):

How does a technical writer build a super-productive relationship with an engineering team? Sarah has some tips gleaned from working with engineering teams at Atlassian and Google. The tips range from co-location (a fancy word for sitting together) to capitalising on your core skills as technical writer (a sure-fire way of becoming a valued member of the team), and more.

Are engineers keen to update the documentation themselves, and what might prevent them from doing so? See what some engineers replied to these questions.

We’ll close with a group discussion where people can share their own ideas and experiences. If it’s easy, bring your laptop or mobile device along, so that you can contribute to a shared doc.

If you’re an engineer or have another role that touches on technical documentation, come and talk about working with technical writers!


Eliminating the zombie vulnerability – removing passive voice from the docs

If you can insert the words “by zombies” into a sentence, then that sentence very likely uses the passive voice. A colleague recently reminded me of this tip. It made me laugh, and so I thought it’s worth blogging about. If only to share the chuckle.

Here are some examples of zombie-infested sentences, and their equivalents using active voice.

Example 1

Geographic requests are indicated by zombies through use of the coordinates parameter, indicating the specific locations passed by zombies as latitude/longitude values.

Converting passive voice to active:

You can use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

For an even more concise effect, use the imperative:

Use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

Example 2

Latitude and longitude coordinate strings are defined by zombies as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Converting passive to active imperative:

Define latitude and longitude coordinates as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Why eliminate the zombie vulnerability?

Active voice is more concise than passive voice. It’s usually easier to understand.

To me, the most important point is that active voice makes it clear who’s responsible for what. Putting zombies aside, if you use the passive voice your readers may think that the nebulous “system” may do the thing you’re talking about.

Who does what, in this example?

The API can return results restricted to a specific type. The restriction is specified using the types filter.

Answer: The developer has to specify the types in the types filter. I don’t think that’s clear, though, when reading the text. Often the context makes it clear, but not always. Zombies lurk in the shadows, ready to grab the unsuspecting reader.

The distinction between active voice and imperative mood

In the above examples I’ve pointed out the difference between active voice and imperative mood. In technical writing, both are good. The imperative mood is particularly concise and clear, but in some cases it can come across as too abrupt.

Should we ever invite zombies in?

I think there are times when passive voice is OK, or even a good thing. Sometimes a sentence sounds artificial if you attempt to inject a subject. Sometimes the passive wording is a well known phrase that readers will accept and understand more easily than the equivalent active phrasing. For example, what do you think of this wording?

These community-supported client libraries are open-sourced under the Apache 2.0 License and are available for download and contributions on GitHub. The libraries are not covered by the standard support agreement.

Stack Overflow’s documentation should be called samples

I’m thinking “documentation” is a misnomer for Stack Overflow’s new feature. “Samples” would better convey the feature’s purpose and form. A topic is basically a code sample (or a few code samples) with metadata (title, tag) and comments.

Calling it “documentation” led me to expect more of it. I looked for such things as navigation aides, a way to order topics in logical sequence rather than by date/popularity, and more control over the hierarchy of concepts.

I  love the idea of sample-driven documentation, but I don’t think the Stack Overflow platform offers it yet.

For background, see my earlier posts: What does Stack Overflow’s new documentation feature mean for tech writing? and Information architecture of Stack Overflow’s documentation feature.

Information architecture of Stack Overflow’s documentation feature

A couple of days ago I pondered on the effect Stack Overflow’s new documentation feature may have on technical writing. Now I’ve taken a closer look at what goes into a topic and how topics are organised.

At first I found Stack Overflow’s documentation feature a little confusing, both as a reader of the docs and as a potential contributor. I thought the organisation wasn’t “intuitive”, by some definition of intuitive. A deep dive has helped me understand the structure offered by Stack Overflow as a documentation platform. It’s less complex than I’d expected. That’s probably why I couldn’t grok it at first!

TL;DR: Topics are grouped under a tag, such as “CSS” or “Java Language”. A tag represents something that needs documenting. The subject of the tag can be as big or as small as you like – or rather, as big or as small as the community likes. Topics are linked together by the tag and by hyperlinks.

What does a topic look like?

When you create a topic, Stack Overflow offers you an outline to fill in. A topic has the following parts:

  • Topic title
  • Examples – that is, code samples
  • Syntax – a place to call out the most important bits of the code, particularly signatures
  • Parameters – that is, method parameters
  • Remarks – anything that doesn’t fit into the above sections

Here’s a screenshot showing the first few parts of a new topic, titled “Find directions”, in edit mode. There’s some useful contextual help for the topic author.

Stack Overflow documentation - topic creation

I like the fact that code comes first, given that the products being documented are developer products such as APIs and SDKs. On Stack Overflow, the audience consists of developers. A good code sample gives developers context and is often all the developer needs to be able to use the product.

On the other hand, it’s interesting that the “remarks” section is right at the end of the topic, and that it’s called “remarks” rather than something a little more weighty or alluring. Even the ubiquitous “more information” would convey… well, more information about what this section is intended to contain.

Code samples are great, but developers often do need other types of information: conceptual content such as an introduction, typical use cases, overviews, best practices, and more.

How do people tie topics together?

How do readers get a complete view of the entirety of a particular subject on the Stack Overflow documentation platform? Actually, taking a step back, I find myself wondering what that “entirety” might be. It’s up to the community to define the size of the things that are documented, and how those things fit in with other things, big or small.

Documentation is attached to tags on Stack Overflow. These are the same tags as are used for the original Q&A part of Stack Overflow. The tag is the primary mechanism for organising topics. For example, the classic Stack Overflow has a “CSS” tag with tagged questions, and now with tagged documentation topics too.

Note that there’s also a more specific set of CSS3-tagged questions and CSS3 documentation topics, and indeed many other CSS-related tags.

For each tag, you can see the set of available topics on the “all topics” tab, like this list of topics for the CSS tag:

Stack Overflow documentation - list of topics

As a reader, you can order the topics by popularity or by date last modified.

There’s an overview topic for each tag, which in this case is titled “Adding CSS to a Document“:

Stack Overflow documentation - overview topic

Each tag also has a dashboard, which shows requests from the community and changes that need reviewing. If you’re a contributor, you can use the dashboard to manage your own activity. Here’s the dashboard for the CSS tag:

Stack Overflow docs - CSS

As you can see on the dashboard, people can suggest new topics and contribute to existing topics. There are currently 41 topics tagged “CSS”, and 4 requests for new topics. People can also mark a topic as needing improvement.

Getting around the documentation

So, in summary, topics are linked by tags. You can also cross-link within topics, using hyperlinks as is standard in web-based documentation.

The only table of contents is the list of topics on the “all topics” tab for each tag. There’s no other type of navigation, such as a curated left-hand navigation or top-level menu.

As David Vogel remarked, this could lead to interesting new information architecture models. I think there’s room here for Stack Overflow to adapt the new platform in response to the way people are using it. Larry Kunz commented that technical writers can keep an eye on this development to learn more about SEO and findability.

Stay tuned!

What the community thinks of the documentation feature

There’s plenty of discussion, much of it heart-felt, about exactly what documentation should be, and hence what Stack Overflow as a doc platform should look like. Here are a couple of examples:

In conclusion

If Stack Overflow has the resources to put into it, they’ll be able to adjust the new documentation platform to suit the needs of the community. As technical writers, we’ll be able to watch and learn. Exciting times.


Get every new post delivered to your Inbox.

Join 1,717 other followers

%d bloggers like this: