技术文档工程师笔试
As discussed in my previous post, technical writers are a vital part of any team. They focus on creating documentation that helps users experience the product more autonomously. However, as also discussed in that same post, regardless of having technical writers, engineers/developers still need to write documentation for more technical audiences.
正如我之前的文章所讨论的那样 ，技术作家是任何团队的重要组成部分。 他们专注于创建文档，以帮助用户更加自主地体验产品。 但是，正如同一篇文章中所讨论的，无论有没有技术作家，工程师/开发人员仍然需要为更多的技术读者编写文档。
At Feedzai, we have technical audiences, such as support teams who specialize in configuring the end-users’ product. Although not being a client per se, these support teams are usually the first users of the product and are the ones that are in direct contact with our actual clients. So they must have all the tools to show the product’s quality to our clients.
在Feedzai，我们拥有技术受众，例如专门配置最终用户产品的支持团队。 尽管本身不是客户，但这些支持团队通常是产品的第一批用户，并且是与我们的实际客户直接联系的人。 因此，他们必须拥有所有工具来向我们的客户展示产品的质量。
A few months ago, I started working with one of Feedzai’s product teams. After a few weeks of working with this team, I realized that our engineering team received daily requests from the support teams to help them configure the product’s different features.
几个月前，我开始与Feedzai的一个产品团队合作。 与该团队合作数周后，我意识到我们的工程团队每天都会收到支持团队的要求，以帮助他们配置产品的不同功能。
Why don’t they use our documentation? Everything they need should be there, right?
他们为什么不使用我们的文档？ 他们需要的一切都应该在那里，对不对？
It should, but it wasn’t. This product’s documentation was more significant and complex than the documentation that I had seen while working with other teams. Also, this particular product team hadn’t had a full-time technical writer for a few months. Naturally, the documentation got a bit out of control. In some cases, there were undocumented or partially documented features. Some elements had complete documentation, but it was in the wrong place; no one could find it. Others were documented in a way that made it hard for the support teams to follow.
应该，但是不是。 该产品的文档比我在与其他团队合作时看到的文档更为重要和复杂。 而且，这个特定的产品团队几个月来都没有专职技术作家。 自然，文档有些失控了。 在某些情况下，存在未记录或部分记录的功能。 有些元素具有完整的文档，但是放在错误的位置。 没有人能找到它。 其他文档的记录方式使支持团队难以跟进。
How can we create documentation that is useful to the support teams?
我们如何创建对支持团队有用的文档？
After informal talks with the engineers, I sent them a short survey to help me understand the issues they faced when creating documentation for the support teams. The survey had these questions:
与工程师进行非正式对话后，我给他们做了简短的调查，以帮助我了解他们在为支持团队创建文档时遇到的问题。 该调查存在以下问题：
- What are your difficulties when you need to produce documentation? 需要制作文档时遇到什么困难？
- (Regarding the revision from the TW) Does it give you the necessary info to improve your documentation? (关于TW的修订版)它是否为您提供了改进文档的必要信息？
- Is there anything that you think could help you produce better documentation? 您认为有什么可以帮助您编写更好的文档的吗？
The results were clear:
结果很明显：
- 72.7% said that they didn’t know where to put the documentation. 72.7％的人说，他们不知道将文档放在哪里。
- 27.3 % said that they didn’t know what content needs documentation. 27.3％的人说，他们不知道哪些内容需要文档。
Taking these results into account, the answer was obvious.
考虑到这些结果，答案是显而易见的。
We need better guidelines.
我们需要更好的指导方针。
Feedzai has 500+ employees. This means that we have a lot of engineers spread across different teams, products, and regions. To have equally efficient and consistent work pipelines, we have a lot of guidelines and policies for various processes. Consequently, when I started this guideline, I didn’t want it to be another complex document that no one really wanted to use. This new document needed to be simple and straightforward.
Feedzai拥有500多名员工。 这意味着我们有很多工程师，分布在不同的团队，产品和地区。 为了拥有同样高效和一致的工作流程，我们为各种流程制定了许多指导方针和政策。 因此，当我开始使用该指南时，我并不希望它成为另一个没人真正想要使用的复杂文档。 这个新文档必须简单明了。
Based on the survey results, I divided the document into four sections:
根据调查结果，我将该文档分为四个部分：
Who should create specific documentation? For example, what documentation should be created by engineers vs technical writers?
谁应该创建特定的文档？ 例如，工程师与技术作家应创建哪些文档？
When should the documentation be created? We looked to specify the key moments when documentation should be updated.
文档应何时创建？ 我们试图指定 文档更新的关键时刻。
How should the documentation be organized? The checklist provided examples of the most common developments and where they should be documented.
文件应如何组织？ 该清单提供了最常见的事例以及应在何处记录的示例。
How should items be documented? We explained how to document each of the sections and deliverables by specifying what each section should and shouldn’t include, and by adding some good examples from the existing documentation.
应该如何记录项目？ 我们通过指定每个部分应包括和不应该包括的内容，并通过在现有文档中添加一些良好的示例来说明如何记录每个部分和可交付成果。
This way, engineers could use the table of contents to go directly to the section they needed without going through the entire document.
这样，工程师可以使用目录直接进入所需的部分，而无需遍历整个文档。
Creating this document turned out to be even more useful than we initially thought as it allowed us to discover inconsistencies in our current documentation, which led to useful team discussions within the TW team.
事实证明，创建该文档的功能比我们最初想象的还要有用，因为它使我们能够发现当前文档中的不一致之处，从而导致TW团队进行了有益的团队讨论。
After a few weeks, we reached a version that we could share with one of the engineering teams. Since they are the ones who will use it, we want their feedback for an interactive process that leads to the document being continuously improved. Ultimately, we want to know if the document indeed helps us improve the documentation delivered to support teams.
几个星期后，我们达到了可以与其中一个工程团队共享的版本。 由于他们是使用它的人，因此我们希望他们提供反馈意见以进行交互，从而使文档得到不断改进。 最终，我们想知道该文档是否确实有助于我们改善交付给支持团队的文档。
Once we receive their feedback, the next step will be to understand how we can extend this initiative to other engineering teams across Feedzai by answering questions such as:
收到他们的反馈后，下一步将是了解我们如何通过回答以下问题来将该计划扩展到Feedzai的其他工程团队：
- Who is the target audience for their documentation? 谁是他们的文档的目标读者？
- Does their audience have any other specific needs? 他们的听众还有其他特定需求吗？
- Does the team have different documentation deliverables? 团队是否有其他可交付的文件？
- Does the team have the same documentation deliverables but with a different purpose? 团队是否具有相同的可交付成果，但目的不同？
- What do their engineers feel when they need to produce documentation? 他们的工程师在需要编制文档时会有什么感觉？
After answering these questions, the focus is to extend the document so that it covers all the relevant cases.
在回答了这些问题之后，重点是扩展文档，使其涵盖所有相关案例。
To sum up, if you are working closely with engineers, always remember that they are not technical writers and usually don’t like to produce documentation. Make sure that they are part of the process, and help them succeed. That’ll pave the way for a happy team, and consequently, a happy customer.
总而言之，如果您与工程师紧密合作，请始终记住他们不是技术作家，并且通常不喜欢编写文档。 确保它们是过程的一部分，并帮助他们成功。 这将为一个快乐的团队以及一个快乐的客户铺平道路。
翻译自: https://medium.com/feedzaitech/how-to-help-engineers-produce-technical-documentation-c9d990febbb7
技术文档工程师笔试
495
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
