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


Grok teamwork and audience


to understand so thoroughly that the observer

becomes part of the observed

Robert A. Heinlein, 1961

Stranger in a Strange Land

Grok


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


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


Web apps

iOS

Android

Desktop

Wearable

youNameIt

Developers.They’re our audience.

Who uses APIs?

APIs

Code libraries

Developer tools


Web apps

iOS

Android

Desktop

Wearable

youNameIt

Developers.They’re our SMEs.

Who creates the APIs?

APIs

Code libraries

Developer tools


What about code?

Code


Which technologies?

Code


What about code samples?

Code

goo.gl/vFqNiq

Collaboration with

engineers

https://goo.gl/vFqNiq

https://goo.gl/vFqNiq


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

http://goo.gl/dT5zF1


Do engineers want to update the docs?

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

Responses



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

Responses



Q: What makes it difficult to update the docs?



Responses


Play with the team


Play with the teamFood

Foosball


Adopt the methodologiesHackathons

Doc fixits

Doc sprints


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


Get to know the tools


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)


Gather and share information


Information sources

Product managers

Software engineers

Support engineers

Sales engineers

Product requirements doc

Design doc

Code - in a shared repo

Demo/sample/test app


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


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

working with an engineering team

Technology