working with an engineering team

Working with an engineering teamSarah Maddox | Write the Docs Melbourne | September 2016

Collaborative notes

https://goo.gl/lfsWnS

Working with Engineers | Sarah Maddox

TL;DR

Sit with the team

Grok teamwork and audience

Play with the team

Adopt and adapt the methodologies

Share the tools

Gather and share information

Working with Engineers | Sarah MaddoxGo for co-location

Working with Engineers | Sarah Maddox

Grok teamwork and audience

Working with Engineers | Sarah Maddox

Grok teamwork and audience

Working with Engineers | Sarah Maddox

to understand so thoroughly that the observer

becomes part of the observed

Robert A. Heinlein, 1961

Stranger in a Strange Land

Grok

Working with Engineers | Sarah Maddox

Explain concepts

Show people how to do something

Publish the terms of service of a product

Notify people of changes and new features

What does a technical writer do?

Help people complete a taskor use a product

Working with Engineers | Sarah Maddox

What does an technical writer do?

Advise developers on naming conventions

Stand up for code readability

Write sample code

Write video scripts

Run workshops, webinars

<

else

<

API

Working with Engineers | Sarah Maddox

Web apps

iOS

Android

Desktop

Wearable

youNameIt

Developers.They’re our audience.

Who uses APIs?

APIs

Code libraries

Developer tools

Working with Engineers | Sarah Maddox

Web apps

iOS

Android

Desktop

Wearable

youNameIt

Developers.They’re our SMEs.

Who creates the APIs?

APIs

Code libraries

Developer tools

Working with Engineers | Sarah Maddox

Web apps

iOS

Android

Desktop

Wearable

youNameIt

Developers.They’re our SMEs.

Who creates the APIs?

APIs

Code libraries

Developer tools

Working with Engineers | Sarah Maddox

What about code?

Code

Working with Engineers | Sarah Maddox

Which technologies?

Code

Working with Engineers | Sarah Maddox

What about code samples?

Code

goo.gl/vFqNiq

Collaboration with

engineers

Working with Engineers | Sarah Maddox

Docs as a team responsibility

Make docs part of the definition of done: goo.gl/dT5zF1

Include doc reviews in standard procedures of engineering team

Share the same issue tracker

Share the same review tool

Take part in code reviews

Working with Engineers | Sarah Maddox

Do engineers want to update the docs?

Q: Are you interested in updating the externally-facing API docs?

Responses

Working with Engineers | Sarah Maddox

Do engineers want to update the docs?

Q: Have you spotted a doc recently that needs updating?

Responses

Working with Engineers | Sarah Maddox

Do engineers want to update the docs?

Q: What makes it difficult to update the docs?

Working with Engineers | Sarah Maddox

Do engineers want to update the docs?

Responses

Working with Engineers | Sarah Maddox

Play with the team

Working with Engineers | Sarah Maddox

Play with the teamFood

Foosball

Working with Engineers | Sarah Maddox

Adopt the methodologiesHackathons

Doc fixits

Doc sprints

Working with Engineers | Sarah Maddox

Doc fixits and doc sprints

Timing

Who to invite

Prizes and food

Doc / code reviews

Bug hot lists or a wish list

Sprint guide

Guide to updating the docs

Progress reports and final wrapup

goo.gl/C41AS6goo.gl/vpmype

Working with Engineers | Sarah Maddox

Get to know the tools

Working with Engineers | Sarah Maddox

Tools you’ll share with engineers

Source repo / version management (Git, Mercurial, Perforce, VSS)

Online repos (GitHub, Bitbucket)

Issue trackers (JIRA, Bugzilla, Trac)

IDEs (Eclipse, IntelliJ IDEA, Microsoft Visual Studio)

Text editors (Notepad++, Sublime Text, Komodo Edit, Vim)

Working with Engineers | Sarah Maddox

Gather and share information

Working with Engineers | Sarah Maddox

Information sources

Product managers

Software engineers

Support engineers

Sales engineers

Product requirements doc

Design doc

Code - in a shared repo

Demo/sample/test app

Working with Engineers | Sarah Maddox

All about information

Discover the developers’ tools for sharing information

Use all channels available

Lurk on code reviews, then take active part

Read code comments

Filter, filter, filter

Working with Engineers | Sarah Maddox

Information - that’s what we’re good at!

Gather it, organise it, share it

It’s what you’re good at

They’ll thank you for it

Info

Working with Engineers | Sarah Maddoxhttps://goo.gl/lfsWnS

The end