文档和开发人员onboarding
构建和支持软件的组织具有许多独特的挑战。他们也有很多常见的挑战。其中之一就是如何帮助新技术团队成员了解技术环境、编码标准、命名约定、代码库、构建和部署工具、版本控制标准和约定等等。
不久前，有人在Twitter上发布了一个问题，引发了一场讨论:
人们回答了一些建议，包括：
请注意该列表中缺少的任何内容？是的，我也是：
当一个图表被美化并准备好分享时，它就像是过时了;当图被润色时，有人提交了一个bug修复。
这是讽刺观察员跳起来喊叫的提示，“你不能依赖只要关于信息的测试套件！“
所以，让我们宣布Snarky观察员“对”，给他们一个很好的糖果作为奖品，让他们落后在我们继续前进的时候在前面的材料中寻找“仅”这个词。
由于一些原因，过多和详细的图表和描述通常没有帮助。首先，由于详细程度，文档几乎肯定会过时。其次，由于这些材料的数量(假设是详细的信息)，新团队成员不太可能阅读全部，即使他们尝试了，也不太可能记住其中的大部分。
那么什么类型的文档可能是有用的，那么？
当我进入一个新的环境时，我发现以下类型的文档是最有用的，最有用的是开始了解正在发生的内容：
- 一种上下文图对于每个主要系统，或者系统的每个主要组成部分都将支持
- 某些线条和盒子的系统主要组件绘制，显示了哪些触摸其它的组件。
就是这样。具体的建模方法并不重要。图形工具并不重要。最有用的图表是高级别的图表。
何时才能达到它并在代码上做一些工作时，我想找到：
- 多级抽象的可执行测试套件，正确孤立
- 在版本控制系统中描述性和有意义的提交消息
- 如果支持语言，则在您工作时，IDES的某种特殊来源评论并在上下文中向您展示rdoc.（红宝石），javadoc.（java），或文件评论(c#)。
就是这样。我永远不会阅读大量的离线文档。我需要帮助在此刻，因此它必须在IDE的编辑器窗格中的上下文中弹出，或立即显示测试结果，也可以在IDE中或命令行窗口中显示测试结果。其他形式的低级文件是浪费。
文档可以解决什么问题？
我们经常与已经运作了几十年的大型组织合作。对于这些组织来说，支持在几十个不同平台上运行的数千个生产应用程序是很常见的。其中，通常有少数是真正关键的任务。目前的系统是在很长一段时间内逐步增加的。随着每个系统被添加到环境中，人们使用当时可用的技术，遵循当时公认的良好实践。其结果是硬件、操作系统、编程语言、软件更新方案、系统配置工具、软件部署工具、安全工具、测试框架等等的混合体。
其中一些是本土产品，一些是第三方产品。其中许多都是旧版本，包括一些完全不支持的版本。随着时间的推移，在交付压力下，人们已经用他们能想到的任何方式将这些系统连接起来。有许多不遵循任何特定标准的点对点接口，在这些接口中，数据在系统之间移动。通常情况下，只有一个人(或根本没有人)理解给定数据传输发生的原因或何时将其添加到环境中。因此，人们担心删除它，担心修改数据格式和数据元素的值。
通常，组织中没有人知道一条数据如何从系统流到系统，从进入环境或创建，直到删除或存档的那一刻。对系统的每一个修改都有一个纹波效果，导致多个其他系统中的回归。即使某些可执行的测试套件到位，也没有实际的方法来预测或防止改变系统的所有意外后果。
在我的经验中，这种情况是文档可以帮助解决的最大问题。“文件”这样，随着上述一些警告，并没有真正帮助个别技术人员与新团队的富有成效。花费了创建详细图表和应用程序代码的低级解释的时间是对记录环境的所有移动部分彼此相互作用的较大挑战的时间。