The document discusses best practices for technical writers working with engineering teams. It recommends that technical writers sit with the engineering team, understand how they work and their audience, and participate in team activities. It also suggests that technical writers adopt the engineering team's methodologies like hackathons and documentation sprints. Technical writers should also familiarize themselves with the tools used by engineers and gather information by participating in code reviews and from other sources to include in documentation.

1. Working with an engineering team
Sarah Maddox | Write the Docs Melbourne | September 2016

2. Collaborative notes
https://goo.gl/lfsWnS

3. 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

4. Working with Engineers | Sarah Maddox
Go for co-location

5. Working with Engineers | Sarah Maddox
Grok teamwork and audience

6. Working with Engineers | Sarah Maddox
Grok teamwork and audience

7. 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

8. 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 task
or use a product

9. 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

10. 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

11. 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

12. 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

13. Working with Engineers | Sarah Maddox
What about code?
Code

14. Working with Engineers | Sarah Maddox
Which technologies?
Code

15. Working with Engineers | Sarah Maddox
What about code samples?
Code
goo.gl/vFqNiq
Collaboration
with
engineers

16. 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

17. Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Q: Are you interested in updating the externally-facing API docs?
Responses

18. Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Q: Have you spotted a doc recently that needs updating?
Responses

19. Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Q: What makes it difficult to update the docs?

20. Working with Engineers | Sarah Maddox
Do engineers want to update the docs?
Responses

21. Working with Engineers | Sarah Maddox
Play with the team

22. Working with Engineers | Sarah Maddox
Play with the team
Food
Foosball

23. Working with Engineers | Sarah Maddox
Adopt the methodologies
Hackathons
Doc fixits
Doc sprints

24. 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/C41AS6
goo.gl/vpmype

25. Working with Engineers | Sarah Maddox
Get to know the tools

26. 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)

27. Working with Engineers | Sarah Maddox
Gather and share information

28. 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

29. 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

30. 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

31. Working with Engineers | Sarah Maddox
https://goo.gl/lfsWnS
The end