We're all responsible for the docs site. Every writer (anyone in the world, actually!) can edit any doc. When you see something that could be better, you should file an issue or, better yet, edit the doc!
But those casual edits by themselves aren't enough to create a world-class product. Great docs need strong product knowledge, born of strong relationships with subject matter experts. That helps us understand user journeys and user experience (in the docs as well as the product), and it's particularly helpful as we design information architecture.
To support that deeper expertise, we break our platform into a number of domain areas and assign each area a level of support:
- Active liaison: A writer is actively developing docs in the area, either for a new feature release or for strategic improvements to the content.
- Point person: A writer is on hand to provide expertise and content review, but we're not actively developing docs.
- Not actively supported: We don't have a liaison or point person, but we'll provide help through the @hero process in #help-documentation.
No matter what support level we assign to an area, the liaison is never the only person to edit! We all share ownership of the site, and you should expect that other writers will edit and contribute to your areas of expertise.
Not every project gets a liaisonship! For smaller projects, we'll encourage teams to edit the docs directly, and then have the hero review their changes. And a smallish project may not need a full liaison—a single ticket might be enough to manage the work.
Liaison responsibilities: Manage project flow
Activity | Who? | Notes |
|---|---|---|
Assign a liaison | Tech Docs manager | When a large new project comes up, the manager will do a pre-scope meeting with the requestor. (Appendix: Project scoping cheatsheet has a list of common questions for this pre-scope meeting.) That conversation helps figure out timeline, complexity, key docs considerations, and which writer will be a good fit as liaison. Once we know we need a liaison, a manager on our team will figure out who to assign. Some of the factors we use to decide who to assign include bandwidth, familiarity with the product or feature, career goals and writing strengths, and simple interest in the topic. |
Manage the project | Liaison | Work with your stakeholders as you define and refine your project plans. As the picture becomes clearer, create tickets in our backlog and schedule them into upcoming sprints. By the time your tickets reach a backlog grooming, you should have a clear sense of scope and resources. (For more on creating a great ticket, see Ticket best practices.) You're likely to take assignment on many of the tickets for your project, but you may also collaborate with other writers and swarm to complete the work. |
Liaison responsibilities: Build expertise
Activity | Who? | Notes |
|---|---|---|
Become the expert | Liaison | Become the Docs Team's local expert on the feature. Understand what it does, what problems it solves, and the implications for our content. |
Educate the team on the feature | Liaison | Part of your responsibility as liaison is to share expertise around the team. That helps with swarming, but it also makes for better hero review and a smarter team that writes more intelligently about the entire New Relic platform. |
Build a relationship with the project team | Liaison or point person | As liaison, you should actively develop relationships with the key contributors in your space. This includes:
|
Liaison responsibilities: Writing and content strategy
Activity | Who? | Notes |
|---|---|---|
Define the information architecture | Liaison | As liaison, you're the expert on both the feature the product team is building, and the docs content (new and existing) that will support that feature. Build an IA that will meet all project needs and scale to the future. For an active liaisonship, that means looking across all the docs and ensuring they read well and connect together into a coherent architecture. If you're a point person, it means building a map in your head of what content is working well and where the opportunities are. You might also bring in smaller tickets into a sprint, or work with your manager if you think we should turn a point person assignment into an active liaisonship. |
Write content | Liaison with support from the team | The liaison writes much of the content for their project, especially the conceptual content like intro docs. But they're not the only ones who can contribute! Particularly when things get busy, we expect the whole team to swarm and contribute to large projects, with the liaison coordinating that work. |
Edit content | Liaison or point person | While many people might edit docs in an area, you're accountable as liaison or point person for the overall quality content. This includes information architecture, voice and tone, and general compliance with our style guide. Ensuring that could include volunteering for peer edit assignments, or tag-teaming with the hero to review an incoming pull request. |