随着公司的成长，文档编制过程从平均的代码注释中演变而来。 在路中间的某个地方，人们通常会出现说他们知道如何正确做事，并且“这本书说明了如何制作文档”，这给公司带来了一些困难的过程。 此外，还有讨论，争议，使用冲突方法链接到不同来源的链接等等。 实际上，这并非偶然。 每当我们遇到这样的时刻，就意味着存在文化差异。 趋势在变化，每个时代都有自己的教科书。
在削减的基础上，我们将与Maxim Tsepkov一起了解从不同的方法中可以学到什么教训，如何设计项目文档，在Wiki中放置哪些内容，适合Google Docs的内容以及必须始终摆在您眼前的内容。 无论如何，为什么我们需要所有这些文档。 同时，我们将涉及知识管理的主题。
文化项目计划
IT行业的历史分为几个阶段，每个阶段都有自己的项目管理方法：关于成功，质量标准，工作组织的想法。 安东尼·劳德（Anthony Lauder）在2008年撰写了《软件项目的文化》一书（链接至
Stas Fomin的
原著 ，
翻译和
审阅 ），其中他确定了四个时期：
它们每个都影响软件项目管理的方法。 没有人想到彼此的一致性。
演讲者简介： Maxim Tsepkov敏捷，绿松石组织和螺旋动力学领域的IT架构师和业务分析师，导航员和专家。我使用了稍有不同的分句，直到现在。 在我提出的方案中，已更改的主要内容是项目的范围。 在研发时代，IT系统在RUP时代能够正常工作-在准时时代，在敏捷时代-能够满足客户需求而不仅仅是工作是很重要的，因为事实证明他们经常做错事。
在现代，IT项目应该为业务问题提供解决方案，并使利益相关者满意。 无论哪种文化划分方案实际上是正确的，都可以使用任何一种，因为差异仅在于细节。
但是，重要的是要了解，大多数文档教科书都是在RUP时代编写的，在该时代，流程的组织旨在满足预算和截止日期。 这行不通，但是教科书仍然存在，
他们没有写新的教科书 。
敏捷在其开发的一开始就朝着相反的方向摆动，宣布工作软件比文档重要得多。 然后是私有格式：用户故事，用例，私有实践，故事映射等，这些都反映在文档中。 但是他们没有编写有关该主题的综合教科书，因为他们知道教科书行不通。
现在我们意识到
项目是不同的，并且
绝对没有通用的配方 -我们需要做适当的事情。 但是，您无需从头开始发明，而需要使用与模板和示例几乎相同的方式来使用模板和示例，例如在界面设计中。 界面是不同的，尤其是在具有小屏幕的移动设备上，您需要放置对于任务重要的东西，没有通用的东西。 但是
有一种样式指南可以提供直观的学习，模式和实践。
在开发样式指南时，他们专注于UX。 文档是相同的-在项目的Doc样式指南上。
我希望该报告将提供一些原理和概念，以便您可以根据这些原理和概念来改善情况并解决项目文档中的问题。
文件-沟通
我从这里开始的主要想法是，文件不是可以自我评估的，而是可以提供交流的。 就像界面本身无关紧要一样，它们为用户提供了隐藏在服务器端的功能。
文件的形式以及界面都是根据沟通的目的而开发的。
在此重要的是，对于长期文档，通信会随时间分布。 今天，您将来会写信给您，将来有必要重新更改您现在正在使用的功能时。 一年半后回到她身边，记住，想一想。 它可以是完全不同的开发人员或操作系统的用户。
并且，如果该文档是交流所必需的，
则应将其
作为针对性 。 有了它，我们就可以与特定的人交流，而不是传播到整个世界。 因此，我们按目的和收件人划分文件：
- 用于决策；
- 当前沟通；
- 及时保存知识（“六个月内送给我”）；
- 向他人转让知识；
- 帮助当前工作等
每个目标都有其自己的描述类型-视点-
其自己的描述方法 。
文件品质标准
质量标准将是文档如何支持为其创建文档的通信。
文件向所有通信方的清晰度很重要 ，这限制了符号的复杂性。 当我们为客户提供类图，业务流程，文档状态时，我们一定不要忘记谁会阅读文档。
UML中的类图是一个非常复杂的符号构造，当仅绘制类和关系时，它以简单的形式几乎是直观的。 但是，当图表中装有各种其他图标时，它很快就变得只有作者和开发人员可以理解。 他们认为他们传达了含义。 客户认为这里的开发人员为自己做了一些笔记，这没有意义，但他们无法删除。 同时，
简化方案应保留关键点 。 值得使用已积累的所有内容：超文本，链接，文本，图形，音频，视频要有效。
方案和模型比文本有效得多 ，因为自然语言是模棱两可的。 经验表明，与文本相比，方案和可视化的失真和误解要少得多。 但是，这些方案必须附带说明，重要的是，这些说明不能重复内容，而只能说明其实质。
有必要创建一个
概念词典 ，一种项目语言，但重要的不是讨论术语，而是讨论内容。 无需争论如何将该词用于某些概念。 我们需要争论在这个主题领域中我们拥有哪些概念和对象，并突出它们。 关于术语多元性及其使用方法的话题，在A. Levenchuk关于系统工程思想的讲座中有很多片段。
设计文档系统时要记住的下一个重要点：
“为什么”和“为什么”比“什么”更重要 。 用例描述了系统中需要做的事情，并且在用户故事中有一个“为什么”部分：“作为
<>我想
< -> ，以便
< > ”。 此外，可以将这种
用户故事格式视为模板，即 所有零件都必须是。 他们并没有立即从经验中浮现出来，但是现在我们知道“为什么”非常重要。 用户故事的目标，任何要求的目标都是客户（用户）与开发人员和分析师之间的时间分布式通信（作为中介）。
在这种时间分散的通信中，传达含义非常重要，这样开发人员才能做出特定的决定。 总是存在无法预料的选择：通过按钮在表单上的位置，通过代码，通过灵活性，通过解决方案的一般性。 如果决定很关键，开发人员当然会打断并澄清。 但是最好是他那时可以自己设置业务任务并做出决定-编码过程中的中断很昂贵。 文档中“为什么”问题的答案很有帮助，这就是它为什么出现的原因。
即使您使用其他格式，也应考虑有关“为什么”和“为什么”的课程-从项目目标开始确定用户和业务的目标。 然后，项目目标的内容通常归结为“出于某种原因需要开展业务”。
无需盲目地做一些企业不了解他们为什么想要的奇怪事情。 通常，他有完全合理的理由，从中挖掘出事实证明，需要完成完全不同的事情。
我们设计项目文件
如何设计？ 像其他任何系统一样。 您需要自己改变的主要思想是，您无需拿走完成的模板并复制它，但是您需要设计一个新的模板，以及如何使用界面来完成它。 依赖于所有种类，有必要采用和设计系统的接口。
接下来，我们重点介绍通信案例，确定将支持它们的文档。 如果通信是随时间分配的，那么您需要一个负责维护文档和有效接受文档的人员。 因为，如果三年后我们发现描述不是很容易理解，那么这种反馈将有点迟了，将没有人传递。
在使用过程中，我们进一步评估质量，并以与可用性和用户体验相同的方式对其进行改进。
要设计，您需要电路。
V-模型是一个方便的方案，该
模型将项目链显示为抽象示例，然后交付结果。
如果在这个模型中我们放置了客户与团队之间交互的经典工件，那么就会有：需求，开发任务，测试用例，
PMI和版本。 工件将有某种负责任的积压。
不是您需要这些文件的事实。 这尤其适用于需求和开发任务。
例如，有一种替代方案-域驱动设计，根据该方案，系统模型代替了需求和开发任务，而被用作集体工件。 该模型反映了系统，该模型一方面由分析师执行，另一方面由开发人员执行。
有许多这样的选择和实践。 所有这些都与开发过程紧密相关，因为正是在此过程中产生了交流。 查看您的过程，并使其适合工件。
V模型是R＆D和RUP时代的遗产。 从那时起，文化发生了变化，现代设计更加广泛。 取而代之的是诸如用户需求和商机之类的事情。 在右侧，而不是一次性维护，而是交付了下一个版本并及时提供了持续支持。
要求条件
在概念和项目开始之间通常存在一个关键工件-
概念或Vision ，它捕获了项目的开始位置。 随着项目的发展，我们将与该概念相关联，但最重要的是，在此基础上一开始就决定是否进行该项目。
在功能上确定应详细制定概念或构想的程度：应使文档尽可能短，因为要尽快完成，但要使利益相关者对项目的开始做出决定。 通常，该概念应反映：
- 项目理念-商业机会：做什么，为谁做和如何做；
- 这个想法的可行性和可行性；
- 主要利益相关者对项目结果的兴趣和期望；
- 产品设计和预期用途；
- 评估项目所需的资源。
此外，兴趣和期望可能会发生变化，如果发生这种情况，及时解决它很重要。
在处理需求的过程中，诸如
项目外部边界之类的事情很重要。 随着文化的变化，关于它的想法从系统设计的一部分功能（在R＆D时代）变为功能作为在自己内部做某事的系统的功能，现在功能对于用户来说是一种价值。 这些是不同级别的工件；它们负责不同的专业领域：架构师，系统分析师，业务分析师。 但这是系统的一种功能方法。
如果我们谈论用户满意度，那么那里也出现了一系列专业化：负责用户对外观的满意度，关于使用的可用性的UI设计师和负责直观界面可维护性的UX专家。 这个边界也在变化。 在您的特定项目中，它可能会有所不同，因为企业发展是一回事，为此需要培训系统，并且用户不会像1C会计师那样走到任何地方，因为这是他的工作场所。 还有另一件事，例如移动开发。 如果商店人员的流动使卖方或店主平均工作3-6个月，那么在2天而不是2周的培训中开发移动工作应用程序的问题就很重要。
维护要求应与测试方法一致，反之亦然。 如果您具有“需求和体系结构”的经典要求，则可以进行“测试驱动设计”，而“行为驱动设计”则不太可能。 因为BDD旨在确保您为用户制定方案，即达到更高的抽象水平。 如果需求中没有场景，那么没有地方可以取而代之。 必须考虑这种关系，还应
控制维护和检查测试用例的
成本 。
自定义焦点工件
专为日常个人关注而设计的单独类别的工件。 例如，这些是
印制并悬挂在开发人员房间前面的电路。 敏捷的课程之一：
任务板和燃尽图 ，物理上挂在房间里或配置有电子格式的热键，非常有帮助。 分心的思想，偶然的粘住，信息不断更新。 同样，对于架构方案，重要的原则。
没错，事实证明，如果您将推荐的所有物品都挂在墙上，它们会变得非常挂机，以至于在您失去视线之前专注于文档的意思是，它们被视为墙纸。 从这个意义上讲，“什么挂在墙上，什么文物将永远摆在您的眼前？”这个问题。 也是需要解决的设计问题。 显然，重要的事情应该挂起。
ER图，应用程序的分层图或主要组件在文档中。 但是，始终躺在文档中或始终挂在墙上是一个很大的区别。 当开发人员认为：“但是不要倾斜地在分层模型的顶部在API上挖一个洞吗？”，因为这确实会减少特定功能的开发时间（但伴随有伴奏），同时该方案挂在您的眼前，那么很可能他会看到那将是一个洞。 如果该图在文档中的某处，那么您可以暂时将其忽略，并快速编写违反该体系结构的代码。
项目运动知识
在Scrum流程中，有一些特殊的点可用于生成有关项目运动的知识：
- 演示-向使用您的工作结果的人和其他感兴趣的人介绍项目的状态。
- Retro是一种自我评估：我们是否工作正常以及可以改进的地方。
- 日常会议-同步团队对项目进展的想法。
- 规划-意图的同步。
重要的是，这些交流会议必须间隔开并集中于各自的目标。 此外，还为它们开发了格式。 整本书中都有关于如何进行回顾以及应该伴随哪些文物的书籍。 此外，某些工件（如代码）是端到端的，因为需要一起计划的任务来自复古。 相应地，该任务的回顾合计为积压，但是例如用颜色标记。 我们与另一方合作-这很正常。
长期描述
创建长期描述时，主要问题是确定
描述将支持的情况 。 选项可以完全不同：
- 教新用户使用系统。
- 提供有关系统罕见功能的参考信息。
- 向新开发人员介绍系统的概念设计。
- 为了帮助召回系统的设备片段，请作者进行改进。
- 描述由新开发人员开发的设备模块系统。
- 向支持工程师提供有关系统设备的信息。
从这个意义上说，您首先要制定需要支持的任务，然后再制作具有必要详细程度的文档，依此类推。
通用描述是详细，昂贵，不相关且也不必要的，因为由于其详细信息而无法在其中找到必要的信息。
有必要
固定目的 ，评估合规性，切记：文件越详细，成本就越高。
一个典型的问题：与客户定期举行的小型会议的记录应该仅对参加会议的人员来说是清楚的，并且使讨论的内容回想起，还是可以将其发送给未参加会议的每个人，并且他们也可以弄清楚呢？ 这是一个重要的问题。
显然，更
详细的协议要昂贵得多 。 必须对此进行管理，并且可能需要进行权衡。 例如，在协议中输入简短摘要，然后参考录制的视频或音频以获取详细信息。 它确实非常有用，许多返回到录像中。
同时，回到“为什么和做什么”，我们不会忘记在摘要中固定决策的逻辑，而不仅仅是“做什么”。 简要地说，但这很重要。
使用符合GOST的规范必要文件，您需要了解交付项目或其他事项是否需要这些文件。 通常，规范性文件可确保客户与检查员之间的沟通，并应在必要的卷中写明，并考虑到客户的使用。 有时这些是只写文档。 例如，我们有一些客户，他们的工作文件和检查员的文件是分开制作的。 但是，有些人希望对文档进行检查是基本的。 依赖于此，文档编制过程有所不同，但是只要我们了解了其目的，一切就很好了。
交流传达意义
让我们离题并讨论交流传达的意义。
一切都始于RUP时代的假设，这催生了面向对象的方法（OOP）。 如果将世界分解为
对象和联系 ，我们将获得清晰无误的世界图景。
客户可以将世界视为Haskell模型中交换消息的交互代理的集合。 代理是相同的，字眼也很清楚，但情况完全不同。 与文本不同，该方案反映了这种差异。 因此，我们使用该方案。
规范是另一种思维方式 。 分层模型是从世界科学发展而来的，其中所有事物都简化为严格的形式并“摆放在货架上”。 如今，随着Internet的发展，世界的思想作为带有连接
的标签云而流行起来，甚至有一个特殊的词
“ folksonomy” 。 这种思考是有效且可操作的。 营销，媒体就是以此为基础的。 越来越接近世界科学景象的IT工程师世界正日益面临这一问题。
从这个意义上讲，您需要
了解并解决思维上的差异 。 否则，您将制作一个正方形系统，客户将为其准备一个圆孔。 然后，合并过程将开始，您将不得不忍受一些水滴状的鳄鱼，因为方形图案的一个角不能被切掉-它是由坚固的建筑金属制成的。
做什么是可以理解的。
绘制图表 。 我们必须采用现成的知名资源，例如UML。 但是请记住，并不是每个人都能很好地理解正式的记号，并且许多人只将粗略的非正式计划视为图片。
IT之外的方案的正交来源是SMD方法（请参阅
“具有不同思维结构的通信-分类法与民俗疗法”的报告 ）。
文件管理原则
1.该文件没有作者。他的寿命比第一作者的寿命长，因此我们共同努力，并且
不使用
信件转发 ，而是使用Wiki系统。 您也可以使用Google Docs，但是有单独的文档，这并不总是很方便。 对于短命的作品，Google Docs很棒。
一个重要的结果来自于这样一个原则，即文档没有作者，也没有在Wiki系统中的经验：我看到了可以改进的地方，马上去做，只有通过分歧才有必要进行协调。
似乎每个人都知道没有作者，但是很少有人纠正别人的文档。 拼写仍然可以，但是如果事情更复杂，那么作者需要去写。 不，
您需要采取并修复它 。 所有Wiki系统都有通知。 如果作者对文档感兴趣，他将看到一个通知，查看更改历史记录，并解释您的输入是否错误。 但是在大多数情况下，他要么不会注意到，要么会决定通常会解决的问题。 维基百科的成功就是如此。
2.逐步创建文档。大型文档在写入之前已过时。 简洁的概念和必要的细节就足够了。 我们处理与当前任务相关的文档部分。
敏捷带来的格式：用户故事，用例，故事映射，与以前的单片产品不同，没有立即出现。 他们专注于增量创建文档，详细阐述。 它们并不是无处不在，但是一旦我们决定逐步提交并详细描述文档，就会对工件的结构和代码施加相同的限制。 一旦我们逐步编写系统并且没有完全调试它，我们就应该相应地组织代码：组件体系结构，微服务体系结构-有很多选择，但不是一个整体。
3.内容比形式更重要。正式文件要求不起作用。 可以一开始就采用它们来节省时间，但这不是质量标准。 利益相关者使用文件适用性的标准是：清单和专家评估。
在这一点上，法规不起作用-这是IT行业而非IT行业发展的教训。 任何人都可以在Wiki系统中进行编辑，没有漫长的批准过程，等等。 在许多OpenSource项目中，提交策略也是如此。 当然，有批准等，但这是应该使用的物化体验。
4.我们留下痕迹。另一个重要原则涉及会议纪要，对话摘要。 也就是说，我们在任务跟踪器中实时聊天，聊天并写下1-2个句子的摘要。 , , -, , .
. , , ,
. . , , . - , . , .
— , , .. , - , -, , , , . : , .
:
- Archimate.
- Archimate.
- - , Domain Driven Design.
- OMG Essence.
- viewpoint' ISO 42010.
. , , .
, , . , , , , , , , , : , .
, Wiki — , , , , , .. , - . CUSTIS MediaWiki. , Jira Confluence, OpenSource http://4intra.net. , , wiki- , .
— . Slack, Task Tracker Google Docs, .
. , wiki. wiki git, - wiki- , .
— , .
, , .
,
« » . , : « , ?» , . , , « » , British Petroleum. , , , .
. .
, .
, , 5–7 , . .
, , , C# , . .
—
. — , wiki — , . . , , , . , , .
— , . BBC , , , . , , . , , .
IBM: — .
IBM : , - , . , . IBM , . , , , , , , , « , , ». . — , , .
mtsepkov.org (, , wiki)
,
agile ,
.
— . , : , , , , Knowledge Conf .
25 TeamLead Conf . , .