Collaboration Between Technical Writers and Developers

技术作家和开发人员之间的合作

2023-11-09 02:25 clickhelp

本文共1536个字,阅读需16分钟

阅读模式 切换至中文

To create truly effective documentation, technical writers and developers need to collaborate closely despite the fact that they usually have slightly different priorities. Writers aim to produce comprehensive docs that aid end users. Developers focus more on building and shipping robust software. This inherent mismatch in goals can lead to friction: developers may resist allocating time for documentation, while writers can feel blocked from contributing to the project. That's why it's critical for tech writers to establish strong collaborative relationships with developers. When writers integrate closely with dev teams and workflows, it eliminates friction and alignment issues. The result is documentation that is timely, accurate and meets the needs of users and the business. This article will provide some practical tips for technical writers to collaborate more effectively with software development teams. By learning how to partner more effectively with developers, writers can create documentation that is of high quality, easy to produce, and aligned with product needs. The key to success lies in establishing shared documentation goals, integrating into development cycles, mastering dev terminology, and building trust through reliable execution and mutual understanding. With tighter collaboration, tech writers can partner with developers to build products and documentation that enhance the user experience. Align on Documentation Goals First, make sure that you and your developers agree on documentation goals and timelines. Technical writers should schedule regular working sessions with the engineering team to establish clear documentation objectives and requirements so that everyone on the team has a shared understanding of what's required for success. During these meetings, writers can explain the importance of comprehensive docs for enabling user adoption and satisfaction. Developers can share their specific workflow and technical constraints. By figuring out the overlap between user needs and developer priorities, the team can agree on achievable goals. This helps get buy-in from developers on taking documentation seriously. Best Practices Negotiate timelines for doc reviews, feedback cycles, and approval milestones. Define required deliverables like API references, release notes, and tutorials tailored to developer tasks. Schedule regular syncs to re-evaluate goals as priorities shift. Integrate Documentation Into Development Cycles Encourage the integration of documentation into the overall product development cycle. The worst case is when writers are brought in at the end of the process to quickly document a finished product. This results in subpar rushed content. Emphasize the need for ongoing collaboration right from the beginning. Advocate for writers to participate in design discussions, sprint plannings, and daily standups, which allows writers to gain context on new features and stay in lockstep with the engineers. As code is written, documentation can be drafted and refined in parallel. Best Practices Negotiate documentation review checkpoints after each development milestone or sprint. Push for developers to include documentation comments as they write code. Have regular syncs with key engineers to debrief on progress. Demo new features often to experience them firsthand while still in development. Leverage Developer Artifacts Take advantage of all the artifacts created during software development. Early access to design documents, product requirements, UI mockups, and engineering diagrams provide valuable insider technical context that aids writing. Encourage developers to include explanatory comments for documentation within the code. Attending design reviews and demos gives writers a chance to ask clarifying questions while features are still in development. Best Practices Ask developers to tag or highlight important sections of code for you to document. Use mockups and prototypes to understand UX flows and illustrate steps. Collaborate with PMs and designers to access strategic documents like PRDs (Product Requirement Documents). Treat JIRA tickets and bug reports as valuable clues to understand functionality. Request developers compile a glossary of key terms and acronyms. Master the Terminology Make an effort to learn the key developer terms, acronyms, codenames, and product-related concepts. One of the biggest challenges for writers collaborating with developers is mastering the complex technical terminology they employ. Getting a better grasp of this terminology ensures that you can write accurately and authoritatively, making you a more credible partner. It also enables the creation of documentation free from confusing errors resulting from gaps in terminology. Best Practices Ask developers to explain unfamiliar terms during conversations. Don't just nod along. Admit when you don't fully grasp a concept and need help. Curiosity leads to clarity. Research terms on your own through available documentation, web searches, and reading. Look for visuals to aid understanding. Maintain a glossary of definitions you can reference. Adopt developer lingo in your own writing when appropriate. Avoid using overly complex terms just for the sake of showcasing vocabulary; keep explanations straightforward and focused on the user's perspective. Request developers review drafts to validate the correct use of terminology. Experience the Product Firsthand Request access to early builds, prototypes, staging environments, and release candidates. Don't just rely on descriptions; instead, seek direct hands-on experience with the product whenever possible. Then, test and demo them frequently from an end user's perspective. Immersing yourself directly in the product provides a grounded user perspective that strengthens collaboration with developers. It also results in documentation that is practical and aligned with reality. Best Practices Verify documentation matches actual functionality during development. Provide feedback on usability issues and confusion points. Ask informed questions based on direct experience. Take screenshots and notes to aid writing. Strive to experience every version, frontend to backend. Use any credentials needed to access advanced features and settings. Leverage ClickHelp for Seamless Collaboration Use an excellent tool for facilitating close collaboration between tech writers and developers – ClickHelp. ClickHelp is an online documentation management platform where you can create centralized source documentation and publish customized versions for different audiences. Snippets and variables empower easily swapping pieces of content in and out of publications. This helps tailor the same core information for different purposes. The platform also streamlines publishing documentation in multiple formats like HTML, PDF, Docx, etc., for easy access across various devices. ClickHelp makes styling and branding documentation simple with ready-made templates. Or writers can leverage custom CSS for more advanced styling. Best Practices for ClickHelp Collaboration Features Have technical writers author, review, and publish all documentation from a unified ClickHelp portal. This centralizes assets and workflow. Assign granular user roles such as contributors, reviewers, power readers, etc. Control who can access and edit what content. Use task assignments, notifications, and project overview features to coordinate team efforts. Enable developers to access real-time documentation drafts as content is being written. This allows early insight and feedback. Facilitate cross-functional teamwork on documentation leveraging ClickHelp's collaboration capabilities. The whole team can contribute. Conduct user testing and gather feedback directly within the ClickHelp platform. Rapidly incorporate real user perspectives. Create customized reports and documentation analytics dashboards to share visibility across teams. By fully leveraging ClickHelp's robust collaboration toolset, you can coordinate your team efforts in creating the best documentation for the best product easily. Try it today – book a free demo. Communicate the Value of Documentation Communicate the benefits of great docs. Many developers are skeptical of documentation because they don't appreciate its tangible value. By highlighting specific benefits like these, writers can motivate developers to prioritize documentation and even participate actively. Benefits of Comprehensive Documentation Enables quicker user adoption and reduces support tickets when self-service answers are available. This allows devs to focus on building vs. support. Increases user satisfaction and retention when people can easily use and understand the product. Facilitates the internal onboarding of new developers by documenting tribal knowledge. Frees up the engineering team from having to create one-off resources for other teams like support, services, sales, etc. Reduces communication gaps across the company by establishing a centralized knowledge base. Ensures best practices are captured and propagated across the organization. Protects intellectual property (IP) and sensitive operational knowledge from being lost when employees leave. Maintain a Constructive Attitude Maintain realistic expectations and avoid taking a lack of engagement personally. Keep in mind that developers often have different priorities and incentives compared to tech writers. Documentation may not be highly valued or urgent for them. Best Practices Accept that docs may not be the development team's top focus. Schedule meetings far in advance when possible to respect busy schedules. If documentation feels like an afterthought, focus energy on delivering exceptionally helpful content within scope constraints. Keep communication professional and solution-oriented. Don't vent frustration at roadblocks. Conclusion Сlose collaboration between technical writers and developers is essential for creating excellent documentation. The key is not to work in isolation but to partner with developers from strategic planning to launch and beyond. This makes it easier to collaborate smoothly. To build a rapport with devs, engage in open conversations about what might be holding them back. Understand their priorities while also communicating the significance of good documentation. If you show you're committed to their success, developers will take a more vital interest in your amazing documentation. The result? Happy users and a team that can be proud of their work because it meets everyone's needs. That's a win-win situation! Good luck with your technical writing! ClickHelp Team Author, host and deliver documentation across platforms and devices
为了创建真正有效的文档,技术作者和开发人员需要密切合作,尽管他们通常有稍微不同的优先级。 作者的目标是制作帮助最终用户的综合文档。开发人员更多地关注构建和发布健壮的软件。这种内在的目标不匹配会导致摩擦:开发人员可能会拒绝为文档分配时间,而作者可能会感到无法为项目做出贡献。 这就是为什么技术作家与开发人员建立强大的合作关系至关重要。当作者与开发团队和工作流紧密集成时,它消除了摩擦和对齐问题。其结果是及时、准确并满足用户和业务需求的文档。 本文将为技术作者提供一些实用的技巧,以便更有效地与软件开发团队进行协作。通过学习如何更有效地与开发人员合作,作者可以创建高质量,易于制作并符合产品需求的文档。 成功的关键在于建立共享的文档目标,融入开发周期,掌握开发术语,并通过可靠的执行和相互理解建立信任。通过更紧密的协作,技术作者可以与开发人员合作,构建增强用户体验的产品和文档。 与文档目标保持一致 首先,确保您和您的开发人员就文档目标和时间表达成一致。 技术写作人员应与工程团队安排定期工作会议,以建立明确的文档目标和要求,以便团队中的每个人都对成功所需的内容有共同的理解。 在这些会议期间,作者可以解释全面文档对于实现用户采用和满意度的重要性。开发人员可以分享他们的特定工作流程和技术限制。通过弄清楚用户需求和开发人员优先级之间的重叠,团队可以就可实现的目标达成一致。这有助于开发人员认真对待文档。 最佳做法 协商文件审查、反馈周期和批准里程碑的时间表。 定义所需的交付内容,如API参考、发行说明和针对开发人员任务量身定制的教程。 安排定期同步,以便在优先级发生变化时重新评估目标。 将文档集成到开发周期中 鼓励将文档整合到整个产品开发周期中。 最糟糕的情况是在流程结束时引入作家,以快速记录成品。这导致了内容的不足。 从一开始就强调持续合作的必要性。提倡作者参与设计讨论、冲刺计划和日常站立,这使作者能够获得新功能的背景,并与工程师保持同步。 在编写代码时,可以并行地起草和完善文档。 最佳做法 在每个开发里程碑或sprint之后协商文档审查检查点。 推动开发人员在编写代码时包含文档注释。 定期与主要工程师同步,汇报进度。 经常演示新功能,以便在开发过程中直接体验它们。 利用开发人员工件 充分利用软件开发过程中创建的所有工件。 对设计文档、产品需求、UI模型和工程图的抢先体验提供了有价值的内部技术背景,有助于写作。鼓励开发人员在代码中包含文档的解释性注释。 参加设计评审和演示给作者一个机会,在功能仍在开发中时提出澄清问题。 最佳做法 要求开发人员标记或突出显示代码的重要部分,以便您记录。 使用模型和原型来理解UX流程并说明步骤。 与项目经理和设计师合作,获取战略文件,如PRD(产品需求文件)。 将JIRA票证和错误报告视为了解功能的有价值的线索。 要求开发人员编制关键术语和首字母缩略词的词汇表。 掌握术语 努力学习关键的开发人员术语、首字母缩略词、代号和产品相关概念。 与开发人员合作的作者面临的最大挑战之一是掌握他们使用的复杂技术术语。更好地掌握这个术语可以确保您可以准确和权威地写作,使您成为更可靠的合作伙伴。它还使文件的创建免于术语空白造成的混乱错误。 最佳做法 要求开发人员在对话中解释不熟悉的术语。不要只是点头附和。 当你没有完全掌握一个概念并需要帮助时,承认。好奇心导致清晰度。 通过可用的文档、网络搜索和阅读,自己研究术语。寻找视觉效果来帮助理解。 维护一个你可以参考的定义词汇表。 在适当的时候,在你自己的写作中采用开发人员的行话。 避免仅仅为了展示词汇而使用过于复杂的术语;保持解释简单明了,并专注于用户的观点。 要求开发人员审查草案,以验证术语的正确使用。 第一手体验产品 请求访问早期构建、原型、过渡环境和候选版本。不要仅仅依赖描述;相反,尽可能寻求直接的产品实践经验。然后,从最终用户的角度经常测试和演示它们。 让自己直接沉浸在产品中可以提供一个基础的用户视角,从而加强与开发人员的协作。它还产生了实用和符合现实的文件。 最佳做法 在开发过程中验证文档与实际功能是否匹配。 对可用性问题和困惑点提供反馈。 根据直接经验提出有根据的问题。 截图和笔记来帮助写作。 努力体验每一个版本,前端到后端。使用访问高级功能和设置所需的任何凭据。 利用ClickHelp实现无缝协作 使用一个很好的工具来促进技术作家和开发人员之间的密切合作- ClickHelp。 ClickHelp是一个在线文档管理平台,您可以在其中创建集中的源文档,并为不同的受众发布自定义版本。代码段和变量使您能够轻松地在发布中交换内容片段。这有助于为不同的目的定制相同的核心信息。 该平台还简化了多种格式的文档发布,如HTML,PDF,Docx等,以便于跨各种设备访问。 ClickHelp使用现成的模板简化了样式和品牌文档。或者作者可以利用自定义CSS来实现更高级的样式。 ClickHelp协作功能的最佳实践 让技术作家从统一的ClickHelp门户网站创作、审阅和发布所有文档。这集中了资产和工作流。 分配精细的用户角色,如贡献者、审阅者、超级读者等。控制谁可以访问和编辑什么内容。 使用任务分配、通知和项目概览功能来协调团队工作。 使开发人员能够在编写内容时访问实时文档草稿。这有助于早期洞察和反馈。 利用ClickHelp的协作功能,促进文档方面的跨职能团队合作。整个团队都可以做出贡献。 直接在ClickHelp平台中进行用户测试并收集反馈。快速整合真实用户视角。 创建自定义报告和文档分析仪表板,以便在团队间共享可见性。 通过充分利用ClickHelp强大的协作工具集,您可以协调团队的工作,轻松地为最佳产品创建最佳文档。立即试用-预订免费演示。 传达文档的价值 传播优秀文档的好处。许多开发人员对文档持怀疑态度,因为他们不欣赏它的有形价值。通过强调这些具体的好处,作者可以激励开发人员优先考虑文档,甚至积极参与。 全面文档的好处 在提供自助服务解答时,可加快用户采用速度并减少支持工单。这使得开发人员可以专注于构建与支持。 当人们可以轻松使用和理解产品时,提高用户满意度和保留率。 通过记录部落知识,促进新开发人员的内部入职。 将工程团队从为其他团队(如支持、服务、销售等)创建一次性资源的工作中解放出来。 通过建立一个集中的知识库,减少整个公司的沟通差距。 确保最佳实践在整个组织中被捕获和传播。 保护知识产权(IP)和敏感的运营知识,使其在员工离职时不会丢失。 保持建设性的态度 保持现实的期望,避免将缺乏参与视为个人行为。请记住,与技术作家相比,开发人员通常有不同的优先事项和激励措施。对他们来说,文件可能不太重要或不太紧迫。 最佳做法 接受文档可能不是开发团队的首要关注点。 尽可能提前安排会议,以尊重繁忙的日程安排。 如果文档感觉像是一个事后的想法,那么就把精力集中在在范围限制内提供非常有用的内容上。 保持沟通专业和解决方案为导向。不要对着路障发泄不满。 结论 技术作者和开发人员之间的紧密合作对于创建优秀的文档至关重要。 关键是不要孤立地工作,而是要与开发人员合作,从战略规划到发布及其他。这使得协作更加顺畅。 为了与开发人员建立融洽的关系,你可以开诚布公地讨论是什么阻碍了他们。了解他们的优先事项,同时传达良好文档的重要性。如果你表明你致力于他们的成功,开发人员将对你惊人的文档产生更大的兴趣。 结果呢?快乐的用户和一个可以为他们的工作感到自豪的团队,因为它满足了每个人的需求。这是一个双赢的局面! 祝你的技术写作好运! 单击帮助团队 跨平台和设备编写、托管和交付文档

以上中文文本为机器翻译,存在不同程度偏差和错误,请理解并参考英文原文阅读。

阅读原文