gcc致命错误没有输入文件_7个致命的文件犯罪

gcc致命错误没有输入文件

文档似乎是运营中的长期问题。 每个人都同意拥有它很重要，但是很少有人相信他们的组织拥有他们需要的所有文档。 有效的文档编制实践可以改善事件响应，加快入职速度并帮助减少技术债务，但是不良的文档编写实践可能比根本没有文档记录更糟糕。

7大罪过

以下任何场景听起来是否熟悉？

• 您有一个Wiki。 还有一个Google Doc存储库。 还有GitHub文档。 在您的主目录中还有一堆文本文件。 以及有关电子邮件中问题的注释。
• 您有一个文档，其中解释了有关服务的所有内容，并且您确定要在某处解决此事件所需的信息。
• 您有一个500行的Puppet清单来处理此服务...没有任何评论。 或评论引用了两个票务系统之前的票证。
• 您有一堆存档的演示文稿，讨论了各种基础架构组件，但是您不确定它们是否是最新的，因为您没有时间来观看它们了。
• 您将一个新成员带入团队，他们花了一个月时间询问各种术语的含义。
• 您在Wiki上搜索并找到了三个有关此服务如何工作的单独文档，其中两个文档彼此矛盾，并且在过去一年中都没有更新。

这些都是您可能犯下了至少一种致命的文档犯罪迹象：

1.存储库过载。
2.埋葬书架。
3.忽略评论。
4.视频成瘾。
5.行话过度使用。
6.文档过度增长。

但是，如果您犯下了这些罪行中的任何一项，您也有可能知道这一罪行：

7.以上一项或多项是正确的，但每个人都说他们没有时间来处理文档。

最糟糕的罪过是认为文档是“额外的”工作 。 这些其他问题几乎总是该错误的结果。 文档编制不是额外的工作，它是每个项目的必要部分，如果不这样处理，几乎不可能做得很好。 如果没有一致的编写，审阅和发布代码的过程，您不会期望从开发人员那里获得好的代码，但是我们经常将文档视为事后思考，我们认为在完成其他工作时会发生这种事情。 如果您认为文档不足，请问自己以下问题：

• 您的项目是否包括将文档编制作为可衡量的目标？
• 您有正式的文件审查程序吗？
• 文件是否被视为团队高级成员的任务？

最糟糕的罪过是认为文档是“额外的”工作。

这三个问题可以告诉您很多有关是否将文档视为额外工作的信息。 如果没有足够的时间来编写文档，或者没有任何流程可以确保所生成的文档确实有用，或者如果文档是针对团队成员的，而对所涉及的主题的掌握程度最弱，那么它将很难生产出像样的东西。

这种经常不屑一顾的态度在业界普遍存在。 根据GitHub 2017开源调查 ，大多数开源项目的头号问题是文档不完整或令人困惑。 但是，其中有多少个项目请技术作家来帮助改善呢？ 我们中有多少人聘请了一名技术作家来帮助编写或改进我们的文档？

实践使（接近）完美

首先，使好的文档成为您的组织所拥护的价值。 正如可靠性需要拥护者优先考虑一样，文档也需要同样的东西。 项目计划和冲刺应该包括交付新文档或更新旧文档，并为此分配时间。 确保人们了解编写良好的文档对他们的职业发展与编写良好的代码同样重要。

此外，可以轻松地使文档保持最新状态，并使人们可以找到所需的文档。 通过这种方式，您可以帮助维持文档的良性循环：高质量的文档可以帮助人们意识到文档的价值，并在他们编写自己的文档时提供遵循的示例，从而鼓励他们创建自己的文档。

为此，请尽可能减少存储库； 一到两个是最佳选择（例如，您可能希望您的运行手册位于Google文档中，以便在公司Wiki停机时可以访问它们）。 如果还有更多，请确保每个人都知道每个存储库的用途； 如果Google文档适用于Runbook，请确认所有Runbook都在那里并且没有其他地方，并且每个人都知道。 确保您的存储库可搜索并保留更改历史记录，并且为了提高可发现性，请考虑添加经常使用的门户或特别重要的文档以方便访问。 不要将电子邮件，聊天记录或票证作为主要的文档来源。

要求团队的新成员和初级成员同时检查您的代码和文档。 如果他们不了解您的代码中发生了什么，或者您为什么做出选择，那么可能需要重写和/或对其进行更好的注释。 如果您的文档不费吹灰之力就很难理解，则可能需要对其进行修订。 技术文档应包括有关流程和行为如何帮助人们创建思维模型的具体示例。 您可能会发现本文中的提示有助于改善文档编写： 10个使文档清晰明了的提示 。

当您编写这些文档时，尤其是涉及到运行手册时，请使用倒金字塔格式 ：最常用或最重要的信息应尽可能靠近页面顶部。 不要将Runbook风格的文档和较长格式的技术参考相结合； 而是将两者链接起来并使它们分开，以使运行手册保持精简（但可以很容易地从引用中找到，反之亦然）。

在文档中使用这些步骤可以将其从精简（或者更糟的是，负担）变成对您的运营团队的乘数。 优秀的文档可以改善包容性和知识转移，帮助您更缺乏经验的团队成员独立解决问题，使您更高级的团队成员有更多的时间从事新项目，而不必进行消防或培训新员工。 更好的是，精心编写的高质量文档使您和您的团队成员可以度过一个周末或度假，而不会在遇到问题时脱颖而出。

在Chastity Blackwell在10月29日至11月3日于加利福尼亚州旧金山举行的LISA17上的演讲“文档的七种致命罪”中了解更多信息。

翻译自: https://opensource.com/article/17/10/7-deadly-sins-documentation

gcc致命错误没有输入文件