如何成功通过技术文档撰写职位面试

所以，您是一位正在求职的技术文档撰写员，并且您需要提交一些写作样本才能进入招聘流程的下一阶段。招聘经理在寻找什么？您能提供什么？以及您能计划好下次准备什么？

您的卖点

每位招聘经理都会收到多份申请，并审查多套文档。作为候选人，您的目标是通过主题明确、考虑周到和引人入胜来脱颖而出。

主题明确

查阅您正在申请的行业类型，看看是否能将它与您现有的任何样本相匹配。如果您正在申请软件安全写作职位，请找到您描述端到端加密或公私钥理论的样本。如果您没有任何真正匹配的样本，请尽可能接近，然后在求职信或单独的样本解释文档中进行解释。如果您是职业生涯中的新手，您可能需要专门为这次面试写一些东西。没关系。您现在写的任何东西都将放入您的作品集中，以便以后取出并进行修改。

考虑周到

您不想把 600 页的文档扔给这位可怜的经理，他已经在阅读很多人的文档了。选择您引以为豪的文档的两到四页摘录。确保您清楚地表明文档还有更多内容，而您只是提供一个样本供考虑。

以可用的格式向人们提供文件也会有所帮助。PDF 几乎总是可以接受的。不要指望任何人手头都有 FrameMaker、DocToHelp 或 Madcap Flare 的副本。您选择的任何格式都必须是可移植的，并且至少在未来几年内不受版本更改的影响。不要对文件进行密码锁定，因为这会降低人们传递文件并将您与其他候选人进行比较的能力。您会惊讶于有多少支持和 QA 负责人最终帮助开发经理做出决策。

我通常会问人们想要多少个样本，但如果他们没有告诉您，请计划至少准备三个样本。

引人入胜

每位招聘经理都在问自己：“这个人能解决我的问题吗？” 如果您回答了那个未说出口的问题，就最容易被录用。AskaManager.org 建议您弄清楚面试官面临的问题是什么，并做好准备告诉他们您将如何解决它。文档招聘也属于这一类，但问题通常是工具、遗留文档和办公室政治的混乱交集。

引人入胜的方法是让他们容易想象您的写作、您的研究风格以及您现有的背景将如何成为团队的有用补充。

不要这样做

错误

不要提交任何有错误的东西。让别人为您编辑它，即使是的，您是专业的。即使专业人士有时也会遗漏一些东西。

许可

不要提交任何您没有权限提交的东西。这意味着，如果它是机密的，它就不能成为您作品集的一部分。如果您在上份工作开始时签署的 NDA 禁止这样做，您可能无法使用该工作中的任何内容。如果您要使用您为他人编写的任何内容，混淆文档的识别细节是必要的，但不是充分的步骤。基本上，如果是雇佣作品，您必须获得书面许可才能声明它，这有时令人沮丧，但这就是流程的运作方式。如果您在良好条件下离职，离职面谈是询问您是否可以带走一些样本的好时机。您可能需要演示如何混淆识别公司信息。

署名

不要抄袭任何人。您可能认为这很明显，但我仍然需要说。招聘经理可以像其他人一样使用 Google 和论文匹配。如果您被抓住，您不仅不会得到这份工作，而且会在您所在的地区（无论是物理区域还是行业）获得难看的声誉。人们会对此议论多年。

不要声称您作为团队编写的某些东西的独有所有权。您需要确定哪些是您单独编写的，哪些是合作编写的。拥有合作编写的文档很有用，只需清楚说明您编写了哪一部分。

理想的样本

根据您的经验水平，您将有不同的可用样本文档集。您的主题不如您经验的广度重要。以下是您可能希望准备样本的一些文档类型

• 程序性/说明
• 概念性（可能带有图纸）
• 发布说明
• 参考
• 周到的索引
• API 文档（您可以将其作为开源贡献来完成。我推荐使用 SwaggerHub 作为工具。）

请记住，您不需要编写完整的文档，您只需提供每种文档的几页。您确实要确保概念文档是一个连贯的想法，而不仅仅是中间部分。

如果您在样本中包含各种技术，那就太好了；例如，一个来自游戏，一个来自 3D 打印，一个来自安全等等。拥有广泛的技术就像将待售房屋粉刷成中性颜色一样。它使潜在的雇主能够想象他们的技术在您的写作中，并证明您足够多才多艺，可以承担他们的产品。如果您有来自公司特定行业的东西，则此样本当然应该包含在内。

示例申请

不要完全复制此模板，因为复制是不礼貌的。

尊敬的招聘经理，

感谢您向我索取样本。我很高兴与您分享我的经验。我为您提供了三个样本。

API 文档是我为 Quill 开源项目做的一个示例项目。我想记录外部开发人员连接到数据源并将其用于自身目的的方式。他们确实在 www.sample.com/api 上有一个公开可用的 API，但它没有任何文档或使用示例。您还可以在此 GitHub 地址以动态方式查看样本：github/me/quillapi。

第二个样本是对公钥/私钥交换的概念性解释。我受到了这个 YouTube 视频（YouTube 链接）的启发，该视频以混合颜料作为隐喻，但我将其重写为关于混合过滤光 以便我可以结合漫射器以及散列的想法。

这些发布说明是一个团队项目。开发人员编写了原始的修复信息，我润色了语言并编写了新功能部分。我团队中的另一位作者编写了安装说明。

我希望这些示例能让您感受到我经验的广度。如果您想查看任何其他类型的文档，或者您想更深入地讨论其中任何一个，请随时与我联系。

谢谢，

有抱负的写作者

其他想法

我还有一些我富有成效地使用的技术，这些技术可能很有用，尽管它们可能不适合申请成为团队初级写作者的人。我的职业生涯大部分时间都是一名独立写作者，所以我不仅需要证明我的写作能力，还需要证明为什么一个组织根本需要一名技术文档撰写员，尤其是像我这样的。

进行文档审核

这仅在组织拥有现有公共文档的情况下才有效。

审查他们拥有的内容，并记下差距或过时的数据。编写一个整洁的内容表，其中记录所有需要添加、更新或删除的内容。例如，您可以鼓励他们删除其产品对不再受支持的浏览器的支持。我不建议在这方面花费超过大约三个小时——毕竟，您是在为他们按规格工作。

展示这个的棘手之处在于找出他们与之前编写文档的人的关系。有时是沮丧的开发人员或非常怀念的前一位写作者。在这种情况下，您需要明确表示他们拥有的东西是非常坚实的基础，您只是建议在这些特定领域工作。但是，如果很明显他们觉得他们被之前的写作者坑了，您可以说：“嗯，以我的专业意见，您真的需要一个快速入门指南，我很乐意为您编写一个。” 永远不要贬低编写文档的人，但要指出您可以为组织改进哪些方面。

展示前后对比文档

如果您可以获得使用这两个文档的许可，这一个可能非常引人入胜。我取一个规范样本、或未记录的 API 或糟糕的 MAN 页面，并将其与我所做的工作并排展示。我准备好谈论为什么我做出这个或那个设计或描述选择，为什么我遗漏了一些东西或包含新信息，我是如何研究新信息的，用户响应是什么样的。进行前后对比确实可以让人们看到写作者的变革性，以及我们如何将一些基本可用的东西变成清晰明了的东西，帮助人们完成工作。

按规格样本

这是风险最高的选择，但可能会有很好的回报。您必须有权访问公共文档，并且它们必须足够糟糕，以至于您在修复它们时会产生显着差异。您还可以独立记录与目标公司销售产品的集成。完成此操作后，您可以结合上述两种方法来展示您可以利用他们提供的产品做什么。同样，您不想在这方面花费大量时间，因为没有人付钱给您。此外，作为一项诚实的检查，您可以将其以 PDF 格式发送，以防止复制。如果有人向您抱怨这一点，您可以问他们为什么要提取您为他们编写的内容。但这仅适用于最有野心和多疑的人尝试。

关于写作测试

您经常会被要求参加写作测试。理想情况下，您应该为您的劳动获得报酬，但我还没有遇到过这种情况。相反，这是无偿时间，就像面试时间一样。

道德的公司会做到以下几点

1. 解释他们期望您在样本上工作多长时间。
2. 给您足够的提前期来处理您有的其他承诺。
3. 只要求您做一些不会直接使他们受益的事情。

如果一家公司要求以下内容，您可能需要拒绝，如果它

1. 要求您编写一些它现在可以在其文档中使用的东西。
2. 给您非常紧迫的截止日期来返回测试，就好像您没有工作和承诺一样。
3. 对您应该在某件事情上工作多长时间提出模糊的建议或根本没有建议。
4. 要求您做一些不道德的事情，例如重新命名受版权保护的材料。

加油！

技术文档撰写是一项了不起的职业，您将学到很多关于产品和人的知识。我绝对鼓励您继续追求它。但是，我们给开发人员的相同警告也适用于此处

• 选择一个看起来您会受到尊重的工作环境。
• 请记住，工作不是家庭，也不是朋友，试图使其看起来像那样会打破权力平衡。
• 您在面试他们的同时，他们也在面试您。
• 我们制造的产品确实对世界产生了影响，但这种影响并不总是好的。自己决定您是否认为您的工作在道德上适合您。
• 这不会是您永远的工作。确保您阅读并理解您签署的合同，以及当您离开时会发生什么。
• 不要接受他们提供的第一个薪资数字——那只是一个开场白。与朋友一起练习说“我希望再多一点”，直到您可以做到而不会惊慌失措。
• 如果您要为一家较新的公司工作，请询问他们的资金来源以及资金还能持续多久。根据我的观察，当公司遇到麻烦时，技术文档撰写员是最先被裁掉的职位之一。

写作者须知

• 您的工作与编码人员同样有价值。许多公司会试图少付给您报酬，但您的行业知识同样有价值，而且您像他们一样操纵符号来创造意义和行动。
• 想成为一名通才，编写公司发布的所有内容是可以的，想成为一名专家，只做文档或只做 API 文档也是可以的。只需知道您对什么感到舒适，因为营销写作是另一种同样困难的专业。
• 当您从事雇佣作品时，您永远不会拥有该作品的所有权，并且您可能无法署名。对于一些一直以来都获得署名的人来说，这是一个真正的转变。
• 如果您认为该作品将是公开的或者您将能够使用它，我建议使用您的姓名或其他标识符作为样本数据，以便您可以自信地指出您编写的内容。它还会显示文档何时更新，并且不再是“您的”了。
• 在您使用数据时要合乎道德且谨慎。尽量确保您的示例中代表各种各样的人——所有性别的人、来自不同语言群体的人、可能代表性不足的人。使用行业标准风格指南，以确保您的样本尽可能通用和易于访问。

想要添加其他提示吗？请留言或在 Twitter 上给我们发推文 @opensourceway。