Where do technical writers fit in an organisation
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.
- Training: See the comment on this post.
- Product services, or a project office: See the comment on this post.
- 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?
Posted on 13 November 2016, in technical writing and tagged technical communication, technical documentation, technical writing. Bookmark the permalink. 23 Comments.
ffeathers 
Great article, Sarah! I believe it is a big benefit for a technical writer to belong to the Engineering and the Product Management team. Being friends with the developers/testers is a win-win situtation for the technical writer as well as the quality of the content. First-hand information of the product from the Product Managers, to detailed insight from the testers, to technical information from the developers, will surely help us in developing the product knowledge.
It is good to be friends with the one from where the information is coming. 🙂
Hallo Altaf
Thanks for your comment! It’s made me think of another possible place we fit in: change management.
In various roles in my tech writing career, I’ve been part of the engineering/product team, part of the developer relations team, part of a change management team, or kind of drifting as a free entity. I think you’re right that working closely with the engineers and product managers is essential in many situations.
The role where I worked in change management was a little different, in that the software changes were made as a result of much larger environmental changes, and these changes integrally affected the processes of the end users. Working with change managers was a very interesting and educative experience.
Cheers
Sarah
That’s a good point, Sarah! In my previous organization, I was also a part of the Change Management team. It is a good entry point to know about the incoming feature requests and bugs. However, this can get a bit overwhelming if you a working on a big product that includes many modules.
In addition, the time that goes into discussing and taking the feature request into production is huge (considering the engineering teams agree or disagree to take it).
Engaging withe the Change Management team, attending the scrums, delivering the content per sprint, the tasks are humongous (we TWs are super efficient 🙂 ).
Greetings from France!
I work with a software firm (https://www.ibe-software.com/) that makes technical writing tools (http://helpndoc.com/).
Thanks for the great article. We’d like to reproduce this on one of our blogs. We’d also be love a chance to collaborate with you on future pieces. Interested?
Hallo Rahib,
Thanks for dropping by! I’ll reply by email to your suggestion of reblogging.
Cheers
Sarah
This is a good read! As a technical writer, I am part of the Training & Development team which used to be in HR but is now within a different business unit. We work in an agile environment so I work with many different business units, but probably closest with IT.
Hallo Stephanie,
That sounds like an interesting group to work with. One that offers the opportunity for you to develop a good variety of material!
Cheers
Sarah
Hi Sarah — good list, thanks! I’m curious about how other writers fit into Product Management when it’s separate from Engineering, organizationally. As a sole writer at a startup, I recently moved from engineering to product (with the hiring of a product exec), and the dust is still settling. I’m finding that I don’t feel as integrated with the development teams as I used to (which may be because my boss is still new, doc is the only thing on his plate that didn’t need attention, and engineering is reorganizing processes at the same time).
In past lives, in addition to support and engineering, I have been part of a training and doc group and also “product services” which included release engineering and QA and reported up through product management.
Hallo Sharon
I’ve tweeted about your comment, hoping some people may have some tips to share about working with a product management team.
Thanks for your 2 suggestions! I’ll add them to the list.
Cheers
Sarah
Hi Sharon,
I’ve found there’s a big difference when I’m part of engineering/development vs elsewhere. Some things that can help:
* If in an agile environment, make sure you attend as many of the meetings as possible. In particular show up to every daily scrum if at all possible. This has two benefits: being more keyed in to what folks are actually doing and reminding devs that you exist
* If possible, ask to sit with the development team or to have use of a secondary desk there part of the time if you can’t be seated there permanently.
* If you cannot sit with the devs, ask to sit right by the kitchen, the restrooms, or the main entrance (if you can handle/not get too distracted by the extra foot traffic). This means that people will continue to see you regularly and give you a chance to grab them as they go by if needed
* Take a walk around the office 1-2x week and (after some basic social chit chat) ask them what they’re working on and how it’s going. This has saved my bacon more times than I can remember.
Thanks, Janice. Those are certainly practices that worked well for me in the engineering group. Good reminders 😉
In my company the documentation team is part of the community department, which manages our product communities and includes all our external documentation resources. Our department works with any other department that requires documentation needs. Initially we did not work as much with engineering and product directly, but over time as our products became larger and more complicated, we had to become more involved with them. Otherwise we wouldn’t be able to keep up with all the changes we needed to document.
For me, I had to set some things in motion to make the interaction happen. I had to find the people who understood the role of documentation and let them know how we needed to be more involved. I told them what would be best for us but was receptive to the engineering team’s time and preferences. My company has a lot of engineering teams so daily standups don’t work for us, but our engineering teams have demos as part of sprint retrospectives, so I attended the demo portion of that meeting. Other opportunities for involvement came later over time. I won’t say making the effort was easy, but our team has been rewarded by being known and respected among engineering, product, QA, support, and account management teams. So start with a small change and you’ll see your efforts expand. Perhaps your boss just needs a little more vision as to how the pieces fit and then you could work together to create a proposed plan for stronger involvement.
The success you have is going to be based on the attitude of those you interact with, and I hope that the people in your company will be receptive to realizing that you are an integral part of your company’s success.
Hi Erin — thanks for the reply. Great input. In my (current) case, I was part of the engineering group for 2+ years before moving to product. There are only a couple dozen engineers, so I’ve already got the rapport in place and am known and respected. I just don’t want to lose that if I’m not an integral part of the engineering organization. I still sit smack in the middle of the open-plan office (per one of Janice’s points).
There’s some concern about me trying to go to “all” of the scrums and planning meetings for 5 dev teams (2 of them are remote), and what’s the best use of my time. The remote teams have mostly been working on internal tech, not user-facing features with doc requirements, but I can’t expect that to always be the case, so I need to figure out a plan that engages with them similarly to the local teams. I do go to the sprint reviews, but often need to be in the loop before something is demo-able.
So I’m looking for good ideas around logistics — meetings, reports (we use Jira and Confluence), sneakernet, etc. When you “told them what would be best for us” — what kinds of things did you ask for?
It’s fascinating to get a glimpse of other organizations’, er, organization!
Hi, Sharon,
What is “best for me” is to have as much information ahead of time as possible. For some projects, achieving this desire has been hard, but we are getting better. I do realize that a product manager’s primary job is not to keep me apprised of every change, and I’m extremely fortunate to have several product managers who keep me in the loop early and often. But in the moments where they forget (because we’re all human and I am not the first priority), I have backups to stay current with everything through Jira and Confluence.
Our Confluence pages include all the information about a project, including all the Jira epics and targeted dates. I also make sure I am aware of each team’s backlog and current sprints, and I also encourage all tickets (when possible) to be associated with the project epic and include a design file. These resources help so I don’t always have to ask about timelines and progress and instead I can focus my questions on small components during each sprint (as I can already tell if the timeline is on track or not). I also attend a UX meeting where the designers show me plans ahead of time and I can learn about workflows before the products are in development.
As a different perspective, some of my team members who work with other products go to every meeting that there is on the engineering side. Others don’t go to any meetings at all and directly communicate with the product manager, who triages the sprint and provides summaries of which Jiras to document and put in release notes.
So I believe your success will just depend on the involvement of your product manager and the scope of your engineering teams’ projects, or more specifically how much information you need from them. Team dynamics (and projects) obviously differ and what may work with one team may not work for you with another. With the products I work on, I have only attended sprint planning meetings with just a few teams, but I have almost always attend demo meetings with every team. Our demo meetings also vary by team—some only demo what can be demoed, while others just all discuss what each person on the team worked on that sprint (that information can also be helpful). And although some of my teams do work on internal tech, eventually that tech will eventually somehow find its way into an external discussion, and I go to their meetings mostly to try and learn more about the technology we are building (if not to help continue to strengthen rapport). So I wouldn’t discount those teams right away; treat them like you treat all other teams and a plan will naturally shake itself out.
I share your sentiment in learning about other companies. Last week I learned that my company is very different in how we create and publish our documentation (it’s all external separate from the code base). I could have felt that we were doing things wrong, but really, success is more about what works efficiently for each company. And sometimes that efficiency medium is tricky to obtain, but I do think it’s possible. 🙂
I am interested in knowing how to become a technical writer. I have academic background in CS.
Hallo somya
It’s great to hear you’re interested in tech writing as a career. Tom Johnson has some advice that you may find useful.
Best regards
Sarah
Hi, I think it is perhaps a misnomer to think in terms of ‘Where do technical writers fit in an organisation. I say this because ‘fitting in’ is compartmentalising a writer, and the writer’s job is so much more than scribbling out documents all day. A technical writer/author is an information consultant (expert). They are available to every department that has a need to communicate information, either internally or externally, they may provide training material and much more. Additionally, they act as a logical source of information and assist with the information needs of others, whether that be through an intranet blog, office memo, API document, visual presentation or providing training. …. Don’t put us in a box!
Hi Nicholas — it’s certainly true that a technical writer can be available to every department that needs to communicate. But in practical terms, we have to fit into the organizational structure/org chart somehow — someone has to manage the writers. Ideally, it’s someone that will help us have the visibility to the groups we need to interact with. I don’t think anyone is looking for a box to hide in when asking “where do tech writers fit,” I think we’re looking for the most accessible and visible spot to reach the teams we need and the teams we serve.
Thanks Sharon, but therein lies the problem for TWs. We are constantly on a mission to ingratiate ourselves within the system that is constantly telling us to buzz off.
The best set-up I had was where we reported to a head of product marketing function, and they sat within the product org (not marketing)
While we worked very closely with the product managers, engineering, support and UX, the product marketing function made us focus very much on writing content for specific personas to support product go-to-market.
This seemed to end up serving all groups perfectly without bias.
Pingback: Where do the technical writers fit? | Leading Technical Communication
Pingback: API Developer Weekly #137 | Restlet - We Know About APIs
Pingback: Where do the technical writers fit? | INFORMAZE