working with an engineering team
TRANSCRIPT
![Page 1: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/1.jpg)
Working with an engineering teamSarah Maddox | Write the Docs Melbourne | September 2016
![Page 2: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/2.jpg)
Collaborative notes
https://goo.gl/lfsWnS
![Page 3: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/3.jpg)
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
![Page 4: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/4.jpg)
Working with Engineers | Sarah MaddoxGo for co-location
![Page 5: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/5.jpg)
Working with Engineers | Sarah Maddox
Grok teamwork and audience
![Page 6: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/6.jpg)
Working with Engineers | Sarah Maddox
Grok teamwork and audience
![Page 7: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/7.jpg)
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
![Page 8: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/8.jpg)
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
![Page 9: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/9.jpg)
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
![Page 10: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/10.jpg)
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
![Page 11: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/11.jpg)
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
![Page 12: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/12.jpg)
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
![Page 13: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/13.jpg)
Working with Engineers | Sarah Maddox
What about code?
Code
![Page 14: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/14.jpg)
Working with Engineers | Sarah Maddox
Which technologies?
Code
![Page 15: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/15.jpg)
Working with Engineers | Sarah Maddox
What about code samples?
Code
goo.gl/vFqNiq
Collaboration with
engineers
![Page 16: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/16.jpg)
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
![Page 17: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/17.jpg)
Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Q: Are you interested in updating the externally-facing API docs?
Responses
![Page 18: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/18.jpg)
Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Q: Have you spotted a doc recently that needs updating?
Responses
![Page 19: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/19.jpg)
Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Q: What makes it difficult to update the docs?
![Page 20: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/20.jpg)
Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Responses
![Page 21: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/21.jpg)
Working with Engineers | Sarah Maddox
Play with the team
![Page 22: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/22.jpg)
Working with Engineers | Sarah Maddox
Play with the teamFood
Foosball
![Page 23: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/23.jpg)
Working with Engineers | Sarah Maddox
Adopt the methodologiesHackathons
Doc fixits
Doc sprints
![Page 24: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/24.jpg)
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
![Page 25: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/25.jpg)
Working with Engineers | Sarah Maddox
Get to know the tools
![Page 26: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/26.jpg)
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)
![Page 27: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/27.jpg)
Working with Engineers | Sarah Maddox
Gather and share information
![Page 28: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/28.jpg)
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
![Page 29: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/29.jpg)
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
![Page 30: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/30.jpg)
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
![Page 31: Working with an Engineering Team](https://reader034.vdocuments.us/reader034/viewer/2022042908/58f2c8ba1a28abaa168b45df/html5/thumbnails/31.jpg)
Working with Engineers | Sarah Maddoxhttps://goo.gl/lfsWnS
The end