尽管第二个月的“编写莫斯科文档”会议于一个月前举行，但发布报告和报告摘要并不为时过晚。 我们设法讨论了几乎所有内容：从记录RESTful API到技术作家的专业发展历程。
顺便说一句，Mitap不仅聚集了“技术贫民窟”，而且聚集了以其他方式以某种方式处理项目文档的其他专家：团队负责人，分析师，测试人员，甚至一名技术总监。
我们的
会议于10月14日（星期日）举行（他进入了关于他的最受欢迎的问题的首位，“为什么在星期日？”）在IPONWEB办公室。 从班加罗尔到旧金山，从伦敦到首尔，Write Docs集会在世界各地举行，该社区的俄罗斯分支仅在活跃，但莫斯科，圣彼得堡和新西伯利亚已经有分支。
安东·特林（Anton Telin），为什么以及如何制作视频说明录影带滑梯Anton管理VLSI的技术文档部门，该部门制作电子文档管理系统。 为什么要录像？ 人们不想阅读说明，他们想解决问题。 人们想向他们清楚地解释。
视频是呈现大量信息，动态实现脚本，一系列动作的便捷方式。 您还可以通过音乐或配音来强调用户的注意力。
如果产品复杂并且没有经过深思熟虑的界面，那么如果没有视觉部分，则很难将其本质传达给用户。 优点是可以减少技术支持的成本。
缺点-不适用于所有出版物格式，很难嵌入到doc和pdf中。 很难搜索。 高质量的视频更昂贵。
另一个紧迫的问题是更新的复杂性，但是Anton的竞选活动解决了这个问题。 他们拒绝录制屏幕录像（屏幕截图），而是使用高质量的屏幕截图。
该公司使用两种视频格式：
视频教学是一系列详细而逐步的动作。 持续时间〜2分钟。 1条指令就是1个问题。 它没有讨论所有的窗口，寒鸦，按钮。 然后添加配音，背景音乐，文字说明和字幕。
2.解释性视频。 这是产品说明和演示的结合点。 没有技术细节的一般视图解决了一些问题或方案。 该视频可能包含人物和动画。 时长2-3分钟。
工具：用于编辑的Adobe Premiere和Adobe After Effects，用于声音的Adobe Audition，用于编辑图像的Photoshop和Snagit。 该项目是由各种屏幕截图组成的，这些屏幕截图不相关或错误，因此很容易替换。 接下来，绘制鼠标的运动，动画，声音。
由于听起来太正式，他们决定使用非专业播音员进行配音，因此他们使用公司的员工Ilya（在Metalcore小组中唱歌）的声音。 在信息块之后，必须给出2秒钟的理解暂停时间。
这些视频会在您自己的托管平台和YouTube上发布。 出于安全原因，许多公司都在阻止它的弊端。
当然，VLSI会收集所有可用的统计信息：平均观看时间，点赞次数，使用视频链接关闭的技术支持电话。
Nikolay Volynkin，技术作家版本2.0.1录影带滑梯这是对SECR会议报告的重复或补充。 尼古拉（Nikolai）看了很长时间的技术作家，发现他们并不总是知道如何证明和衡量自己的利益，而负责他们的领导者们也总是知道。
技术作者可以解决一些相关任务。 尼古拉说，职业生涯的轨迹和技能集有技术说明，以及如何将新任务推销给企业。
技术作家可以扮演的5个角色：
1.
Docops-文档的开发人员，作家/程序员，他可以自动生成，验证，上传文档，训练团队使用它并围绕它重建所有流程。
好处是减少了手工劳动，节省了资源，并且功能交付速度更高。
2.
UX编写器-在界面中编写文本的专家。
好处-设计师，诗歌，分析师或前端开发人员并不总是了解如何正确编写，如何向用户传达功能，按钮，转换。 文字是根据谁先站起来和拖鞋的原则写的。 方便的界面，减少了技术支持的时间。
3.他是一位
技术传教士 ，他谈论技术，与社区互动，塑造技术。
收益-对公司，对产品的信任和忠诚度提高，简化了招聘和HR品牌。
4.
知识经理 -探索公司如何生产，存储和转移知识。 建立这些过程，以便知识不会泄漏。
收益-减少公交车因素，降低员工适应新手和过渡期间的速度，知识重用，降低风险。
5.
文档所有者 -项目经理和文档分析师。 他在文档中构建了整个交流和用户交互系统。
好处是再次降低了支持成本。
在讨论期间，我们回顾了作为内容管理员的综合角色，报告中未提及。
康斯坦丁·瓦列夫（Fonant）录影带滑梯Restrim的Constantine谈到了
Foliant工具-基于Markdown语言的docops工作流程的实现。 一年前，作为
Yandex的
迷你超长棍战斗机的一部分
，康斯坦丁已经谈论过Foliant，此后发生了很多变化。
该文档以MD文件编写，并且位于不同的位置，该工具支持持续集成，自动组装，并且还允许您根据自己的喜好扩展MD。
要求：您需要为客户提供docx，并提供具有良好排版的PDF，并具有易于阅读的资源（非XML）。
在引擎盖下，使用了通用的Pandoc转换器，Python，bash脚本缠绕在顶部。 但是随着时间的流逝，脚本的数量不断增加，因此它们被重写为一个单一的整体应用程序。
然后，他们从整体中创建了一个模块化结构，其中内核控制着程序集，将MD转换为汇编程序工作的预处理器以及汇编程序本身。
泡沫实际上是好的工具（mkdoc，pandoc，slate，latex）之间的粘合剂。 现在，他们正在尝试教授如何使用不同格式的文档资源。
在项目文件夹中，有一个配置文件，其中包含最终文档的结构，样式和实际的MD文件，然后预处理器获取源MD文件并对其进行处理，从而以all.md的风格（所需的md风格为md的风格）制作所需的MD，然后再收集最终文档（ pandoc，mkdoc）使其成为目标（文档）。 MD组装后，运行linters来检查语法。 还发送有关构建或错误的构建通知。
所有这些都可以在Docker中收集，因此所有软件包都以一种方式交付，而不是分别交付。
Foliant支持高级功能，可以从Gitlab / Github中提取代码段以及具有Simpli布局的图像，可以绘制图表，在文本中替换参数，条件语句。
Nikita Samokhvalov，有关RESTful API的综合文档录影带滑梯Notamed技术总监Nikita Samokhvalov告诉他们如何配置基于Open API 3.0的API文档的生成。
像其他所有人一样，他们都是从Google文档开始的，但是它既没有版本控制，也没有创建分支的能力。 然后他们才开始在存储库中编写MD文件，解决了版本控制和创建分支的问题，但是一切都很缓慢。 然后进入自动生成。
该文档具有以下要求：文档片段的继承和重用，提供指向参数和方法的描述的链接，有关访问权限的区别的信息，文档作为代码（同步部署和更改）的能力。 此外，该文档不会公开发布，仅适用于您的团队和研究生开发团队。
我们选择了OpenAPI 3.0规范。 怎么了 它是最新鲜的，支持更多功能，尽管周围仍然只有一个很小的生态系统和专业知识。
他们使用了
shins工具（在漂亮的登录页面中显示了MD文件，并带有查询示例，方法说明，参数），
widdershins （将
Yaml / json转换为MD的转换器），还编写了自己的
specker包（安装了所有必要的依赖项，通过npm进行工作，还检查了文件分配结构的正确性）。
设置环境和组装文档是在控制台中的一行上完成的。 需要在每个项目中重用的文件（例如，授权说明）都属于依赖项/文件夹。
Nikita还谈到了他们如何与分布式团队中的分支机构一起工作，何时要更新文档，当然还谈到了OpenAPI 3.0实施带来的陷阱和困难。
Svetlana Novikova，使用能力矩阵的知识管理录影带滑梯Svetlana（顺便说一句，这就是我）谈到了他们在公司中如何安排从人事管理领域重新启动端到端工具作为胜任力矩阵，知识管理的这种使用方式，该工具如何帮助减少公车因素，最好是登上新手甚至找到零件重构代码。
Danila Medvedev，NeuroCode录影带Danila谈到了一种所有人都可以理解的工具，也许是我们时代之前的工具，它可以用来建模和存储称为NeuroCode的知识。
该工具对参与IT系统设计的任何人都非常有用。 Danila特别建议放弃基于文档的系统。 任何系统都根据其节点传输某些信息的方式被视为网络。 系统的所有元素都遵循此原则-推送更新，文档传输，反馈传输。 NeuroCode的目的是“减少支持流程的非生产性成本，并增强组织的集体智慧”。
NeuroCode项目源于解决问题-如何为团队或您自己创建良好的信息存储库，以及如何创建信息模型。 该系统的原型已制成并可以正常工作，现在正在系统工程师和业务架构师的帮助下对其进行测试。 该系统具有可扩展的接口，并基于分形数据结构。 它也基于道格拉斯·恩格尔巴特（Douglas Engelbart）（这是最早的人机界面研究人员之一，GUI，超文本等概念的作者）关于开放超文档系统（OHS）的思想，当时该系统不是基于文档的，而是一个单一的文档。也就是说，它实现了人类活动的所有过程。
PS通常，最好观看视频。
下一次会议
“ Writing Docs Moscow”将于12月7日在Positive Technologies办公室举行，会议的形式为Positive Authoring Tools Battle。
