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?

Advertisements

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 13 November 2016, in technical writing and tagged , , . Bookmark the permalink. 17 Comments.

  1. 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 🙂 ).

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

  3. Stephanie Majors

    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.

  4. Sharon Metzger

    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.

      • Sharon Metzger

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

  1. Pingback: Where do the technical writers fit? | Leading Technical Communication

  2. Pingback: API Developer Weekly #137 | Restlet - We Know About APIs

  3. Pingback: Where do the technical writers fit? | INFORMAZE

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: