Author Archives: Sarah Maddox
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?
This week we hosted the first ever Write the Docs meetup in Sydney. It was great to see so many familiar faces and to meet so many new people too.
The Sydney meetup
We had 22 attendees at the inaugural Sydney meetup. The venue was the Google offices in Pyrmont.
Swapnil was an excellent host. Between the two presentations (see below) he asked attendees to introduce themselves and say what they liked most about technical documentation or being a technical writer.
What attendees like about technical documentation / technical writing:
- I like to explain things.
- The scope of technical documentation extends all the way from consumers to developers.
- I like editing a doc when someone complains about it – that means they need it.
- I like to help things go smoothly.
- I’m married to a technical writer.
- Technical documentation says exactly what it means. It cuts out all the fluff, even when describing an error in the product.
- I get to do problem solving in a creative environment.
- I like the ability to make the documentation a tool that someone can use rather than just read.
- Technical documentation captures stuff before it’s lost.
- I truly enjoy the research that goes in before writing the docs. Discovering bugs!
Presentation: Integrating more closely with software product teams
Craig Simms, from Campaign Monitor, presented a talk on how technical writers can integrate more closely with software teams. Campaign Monitor works off an agile development process. As processes change, the technical writing team must change to keep up.
Craig’s presentation was amusing and engaging. He told the story of how technical writing started at Campaign Monitor as a community building role, but it quickly became apparent that it was a core technical writing role. Quite quickly, the two writers in the company felt that their role description and placement in the company didn’t reflect the value that technical writers bring to an organisation. They decided they needed to join a product team.
Craig described the two years of adventure he and his co-writer have had, attempting to get into a product team. They’ve not yet succeeded, Craig said with a laugh, but he gave a zestful account of the lessons learned, and the steps they’ve taken towards that goal. One of the questions that’s arisen is this: Is product the right place for technical writers? An attractive alternative is to be part of the marketing team.
This quotation from Craig’s presentation in particular rang true with me:
Define your own value, and never stop telling people.
Here’s the recording of Craig’s presentation:
Presentation: Wrapup of Write the Docs Prague
Swapnil Ogale presented his summary and take-aways from the recent Write the Docs Prague conference.
Swapnil talked about these topics:
- Why he attended the Prague conference.
- Attendee demographics – he showed a lovely picture of the venue and participants.
- Range of topics covered – wide, including fiction and health!
- A deep dive into 2 presentations he found most useful.
- The unconference part of the event – spontaneous sessions on what people wanted to talk about.
- Key takeaways from the conference.
An interesting statistic:
70% of participants are working on dev docs, APIs and UI text.
Here’s the recording of Swapnil’s presentation:
Where next for Write the Docs Australia?
I’ve been lucky enough to attend both meetings of the Write the Docs Australia group. Perhaps I can keep a good thing going and join the third, wherever it may be. Brisbane, anyone? 🙂
I’ve released an update to the Tech Comm on a Map app on Android. You can now share a link to the location of an event via email, chat, Twitter, Slack, and so on – any app on your Android device that shows up in the standard app chooser. The people you’ve shared the link with can use it to open the Tech Comm on a Map website directly at that location. Handy for sharing event information!
Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. You can use it on the website and get the Android app.
New: link sharing
Let’s say you’re looking at the tech comm events in your city, or in a part of the world you’re planning to visit. You want to let a friend or colleague know what’s happening in the tech comm world. Now you can share a link to a specific location on the Tech Comm map.
In the Android app, view an event:
Pull up the event panel from the bottom of the screen, to see the event details. Notice the new Share button:
Click the Share button. Android pops up a standard app chooser, showing you all the apps on your device that can handle the share request. It looks something like this, but you’ll see a different selection of apps:
Choose an app. Tech Comm on a Map sends your chosen app a bit of text and a shortened URL. This screenshot shows Twitter as the chosen app:
Your friends can copy the link and paste it into a web browser, to open Tech Comm on a Map at the location you’ve shared. (In this case, the shared link is https://goo.gl/SjBvRc.)
What’s next for Tech Comm on a Map?
Currently, the shared link opens the Tech Comm on a Map webapp. It’d be great to offer a link that opens the Android app directly at the given location.
The way to do it is via Android intents. I got part of the way to achieving this in the current release. If you click a link of a specific format, the Tech Comm on a Map Android app opens, but it doesn’t open at the given location. So far, I can’t get the location parameters to go all the way through to the app.
There are some other nice tweaks I could add to the app. I’m keeping track of feature requests and bug reports on the GitHub issue tracker. See the issues for the web app and for the Android app. They’re both open source, and you’re welcome to get involved.
For a technical writer, working with an engineering team is fun and rewarding. Sometimes, however, it can be tricky to get the information you need from busy people who are focused on getting all the bits and bytes to play nicely together. How can a tech writer build a productive, mutually beneficial relationship with an engineering team?
I’m delighted to be working with the ASTC (Australian Society for Technical Communication) to present a webinar on working with an engineering team. Dave Gardiner is the organiser and Hamish Blunck is the webinar host.
Here’s a hint: I’ve found that engineers value the art of making words play nicely together too.
Update: Recording of the webinar is now available
A recording of the webinar is now available on Vimeo, and embedded below. Click the play button at bottom left to view it on this page.
Date and time: Tuesday 1st November at 4pm, Australian Daylight Saving Time. (That’s 6pm in New Zealand, and 10:30am in India.)
Registration: See the ASTC webinar announcement. This webinar is free of charge.
I hope you can join us!
So many options to choose from! As a technical writer in Australia, I can join a Write the Docs Australia meetup, the ASTC (Australian Society for Technical Communication), the US-based STC (Society for Technical Communication), and more. I’ve been putting some thought into the differences between Write the Docs on the one hand, and organisations such as ASTC and STC on the other. For me, they all have their place and membership of all of them is valuable.
I’m currently a member of Write the Docs Australia, and have also attended Write the Docs meetups in San Francisco, Silicon Valley and Portland. I’m a paying member of the ASTC and the STC, and support both by presenting at conferences or webinars whenever practical. I’ve also presented sessions at conferences organised by other bodies, such as TWIN and tekom.
For me, Write the Docs differs from the more formal organisations in that it’s an informal community of people interested in technical documentation. 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 join an organisation – you just join a meetup, and then turn up.
Write the Docs is focused on documentation, rather than on technical writing. The community explicitly welcomes anyone with an interest in technical documentation. This includes technical writers, engineers, UX designers, support engineers, editors, and more.
The primary focus of Write the Docs meetups is API docs and developer tools, but other types of tech docs are becoming popular too. It’s up to us, the members of the community, to decide what we talk about.
So, for me, there’s a place for both types of organisation, even in a community of writers as small as Sydney or Melbourne. My aims are to share knowledge, learn, meet people, and spread good cheer.
And I haven’t even touched on the various social media groups and mailing lists on Slack, LinkedIn, LISTSERV, and so on.
What brought on these musings? The first Sydney Write the Docs meetup ever is at 6pm on Thursday 3rd November. Come along if you have an interest in, or a story about, tech docs – from any perspective.
Have an idea for a talk for future meetups? Add questions or comments to this post, or add them as comments on the meetup page. Swapnil Ogale, the founder of Write the Docs Australia, would love to hear your ideas!