流程结构

  1. 一个（过程）问题经常出现在问题或聊天中。
  2. 在对手册的合并请求中提出了建议。
  3. 合并后，通过链接到MR或commit中的差异来宣布更改。主要事项已列入公司电话会议的议程。中号标记将发布在#handbook频道中以供查看，并附上一行的更改摘要。如果有问题，请使用差异链接将其关闭。

有时，您希望在会议期间实时编辑提案，并且需要为此使用Google文档。这样做时，第一项应该是手册页面的URL，会议结束后该内容将移至该页面。

为什么手册第一

开始采取行动之前，在手册中进行记录可能会花费更多时间，因为您必须考虑在哪里进行更改，将其与现有内容集成，然后可能添加或重构手册以具有适当的基础。但是，从长远来看，它可以节省时间，而这种沟通对于我们继续扩展和适应组织的能力至关重要。
此过程与为软件编写测试无异。仅通过对手册的更改传达（建议的）更改；请勿使用演示文稿，电子邮件，聊天消息或其他媒介来传达更改的组成部分。这些其他形式的交流对于演示者来说可能更方便，但是它们使听众更加难以理解上下文和对其他可能受影响的过程的影响。
拥有“手册第一”的心态可以确保没有重复；该手册始终是最新的，而其他人则更有能力做出贡献。

手册指南

请遵循这些准则，并提醒其他人。

我们每天如何使用指南

  1. 除非另有说明，否则本手册中的大多数准则都旨在提供帮助，而不仅仅是绝对的规则。不要害怕做某事，因为您不了解整个手册，没人知道。提醒人们有关这些准则时要保持谦虚。例如，说：“这不是问题，但是下次请考虑手册中的以下准则。”
  2. 如果您提出问题，并且有人通过手册的链接进行回答，那么他们这样做是因为他们想通过提供更多信息来提供帮助。他们也可能为我们记录了答案而感到自豪。这并不意味着您应该已经阅读了整个手册，没有人知道整个手册。
  3. 如果您需要向团队成员寻求帮助，请意识到大多数社区中的一个很好的机会也不知道答案。确保记录答案，以将这些信息传播给整个社区。回答问题后，讨论应在何处记录该问题以及由谁进行记录。您可以通过询问“谁将记录此文件”来提醒其他人此请求。
  4. 在聊天中讨论某些内容时，请始终尝试链接到相关的URL。例如，您有疑问的文档或回答您问题的页面。您可以询问“您能否链接？”来提醒其他人。
  5. 请记住，手册不是我们希望做的，不是我们应该正式做的，也不是我们几个月前所做的。这就是我们现在所做的。确保更改手册以真正更改流程。要对流程提出更改，请提出合并请求以更改手册。不要使用其他渠道来建议更改手册（电子邮件，Google文档等）。
  6. 手册就是过程。任何带有“过程”，“策略”，“最佳实践”或“标准操作程序”之类名称的部分都表明存在更深层次的问题。这可以指示在过程的散文描述与应该在过程的一个描述中组合的同一过程的编号列表描述之间的重复。
  7. 在进行交流时，请始终包括指向手册相关（最新）部分的链接，而不是在电子邮件/聊天/等中包含文本。您可以通过询问“您能否链接到手册的相关部分？”来提醒其他人。

  8. 每个人都应订阅#handbook频道，以随时了解该手册的更改

    如何更改或定义流程

  9. 要更改准则或流程，建议以合并请求的形式进行编辑。合并后，您可以在公司电话中讨论该问题（如果适用）。您可以通过询问“您可以发送该手册的合并请求吗？”来提醒其他人。

  10. 在大幅更改手册布局时，请保留指向此MR直接影响的审阅应用程序特定页面的链接。与链接一起，在MR说明中包含尽可能多的信息。这将使每个人都可以了解MR的目的，而无需关注差异。
  11. 跟上该手册的更改可能很困难，请遵循提交主题指南，特别注意合并请求的标题，以确保阅读该手册Changelog的人可以快速理解MR的内容。
  12. 通过链接到合并的差异（一个提交来显示更改前后的提交）来传达流程更改。如果出于讨论和反馈的目的交流变更，可以链接到未合并的diff。不要先更改流程，然后再将文档视为优先级较低的任务。以后计划做文档不可避免地导致重复的工作来传达变更，并且导致文档过时。您可以询问“您能否先更新手册”来提醒其他人？
  13. 像其他所有事情一样，我们的流程总是在不断变化。一切始终在草稿中，初始版本也应在手册中。如果您打算对手册进行更改，请尽可能跳过该问题并提交合并请求。（相比问题描述，建议通过合并请求提出更改）。在合并请求中提及受更改影响的人员。在许多情况下，合并请求更易于协作，因为您可以看到建议的更改。
  14. 如果某项测试仅对一组用户有效，请将其添加到手册中并记录下来。测试结束后，请删除注释，每种情况下都应使用新流程。
  15. 如果GitLab内部或外部的人提出了很好的建议，请邀请他们将其添加到手册中。向该人发送相关页面和部分的URL，并在他们无法做到的情况下主动为他们提供该URL。让他们提出并发送建议将进行更改并反映他们的知识。
  16. 提交合并请求时，请确保它被快速合并。快速进行单个小的更改将确保您的分支不会落后于master，从而导致合并冲突。旨在在同一天制作和合并您的更新。在合并请求中提及人或通过Slack与他们联系。如果您在现有建议的基础上获得了较大改进的建议，请考虑单独进行。创建一个问题，合并现有的MR，然后创建一个新的合并请求。
  17. 如果必须移动内容，则有一个合并请求，该请求会移动它，而不会执行其他任何操作。如果要清理，总结或扩展它，请在移动MR合并后执行。这很容易检查。

  18. 尝试添加手册过程的原因，什么是业务目标，什么是本节的灵感。添加“为什么”可以使以后的流程更容易更改，因为您可以评估“原因”是否已更改。

    风格指南和信息架构

  19. 单一真相考虑消除重复并拥有单一真相（SSoT）的信息体系结构。与其重复内容而不是交叉链接（每个文本都有到另一部分的超链接）。如果您复制内容，请在原始位置将其删除，并用指向新内容的链接替换它。重复的内容导致必须进行多项更改来更新它，这是一项繁重的工作，而且很容易忘记。如果您忘记了其中一部分内容，则该内容已过期。

  20. 如果有相关项目（手册，文档或问题的其他地方），请确保始终交叉链接项目。
  21. 该手册按功能和结果进行组织，以确保其中的每个项目都具有位置和所有者，以使其保持最新状态。
    • 重要的是，我们必须遵循这种层次结构，并且不要为公司的培训材料（例如，入职材料，操作方法等），视频或其他文档维护单独的结构。
    • 坚持这种等级有时是违反直觉的。多年来，我们已经了解到，将内容保留在上下文中有助于确保将来进行更新时的一致性。
    • 有时可能需要改变视角。在这种情况下，请链接到手册的相关部分，但不包括内容本身。请参阅入门模板作为示例。或例如，关键绩效指标的列表，这些列表链接到绩效指标，但不重复定义。
    • 避免基于常见问题解答，链接列表，资源页面，词汇表，课程，视频，测试或操作方法之类的格式的非结构化内容。这些很难保持最新状态，并且与每个职能和结果的组织都不兼容。
    • 而是将答案，链接，定义，课程，视频或测试放在最相关的位置。使用描述性标题，以便人们可以轻松地搜索内容。
    • 也就是说，请在手册中的适当位置和时间混合格式，即使在一页内也是如此。使用多种格式可能很有价值，而且不同的人可能会更喜欢某些格式。
    • 仅担心每个功能和结果的组织，而不担心如果您嵌入各种类型和格式的内容，页面的外观。
  22. 自由使用标题。如果页面包含两个以上的标题（尤其是它大于单个“屏幕”），则通过在此MR中复制第6行到第10行来添加自动生成的目录（ToC ）。
  23. 强烈考虑学习如何使用git和/或通过Web IDE编辑手册，并在撰写之前请通读《写作风格指南》。

    细点

  • 手册要简短明了。消除绒毛，并以尽可能短的措辞直截了当。请记住，新员工提出的最大挑战是在入职期间要吸收大量信息。
  • 我们的手册中不需要.gitkeep文件，它们使在编辑器中快速打开文件变得更加困难。不要添加它们，并在看到它们时将其删除。
  • 在终端中完成比拼写更正的工作要比使用在线编辑器更好。所有不愿更新手册的人都没有使用终端，本地编辑器和本地预览。请按照本地编辑此网站中的说明进行操作。

  • 当提及团队成员可能需要转换为当地货币的货币金额（例如，福利，费用或奖金）时，请将这些金额链接到我们的“ 汇率”部分（例如500 USD）。

    本手册的范围

  • 所有也适用于来自更广泛社区的代码贡献的所有文档都应该在GitLab CE项目中（例如，在CONTRIBUTING或代码审查指南中），而不是仅适用于团队成员的手册。在手册的文档部分中阅读更多内容。

  • 该手册仅适用于当前和将来的GitLab团队成员。如果有任何有关GitLab用户的问题，则应在GitLab文档，GitLab开发套件（GDK），CONTRIBUTING文件或PROCESS文件中进行记录。

    移动页面并将重定向添加到手册

    该手册是一份实时文档，有时我们需要更改URL或移动页面。这是数字营销用来为about.gitlab.com 设置和管理重定向的过程。

    管理

    确保手册保持最新是每个部门和团队成员的责任。人事运营专家将与每个部门（工程，市场等）的代表合作，通过每周审核，以确认手册中的内容准确无误，并遵循《指南》中概述的相同格式。有关向谁提交合并请求或对手册提供帮助的问题，请访问“ #handbook” Slack频道。
    如果您需要权限来直接将更改合并到手册中，请提交新的访问请求问题，并按照流程进行访问批准。在www-gitlab-com下请求一个“维护者”角色。有关角色和权限的完整说明，请参见此处。
    在本评论中，手册的任何更改都将#handbook在Slack 的频道中共享。人员运营专家还将确保#questions记录询问的问题，并且公司电话上的所有公告均具有相关链接。

    屏幕共享手册，而不是创建演示文稿

    演示非常适合临时内容，例如小组对话和董事会演示。常绿内容（如领导力培训）应以手册为基础。请屏幕共享该手册，而不要为常绿内容创建演示文稿，因为：
  1. 它节省了您创建演示文稿的工作。
  2. 人们稍后可以轻松找到手册部分。
  3. 作为准备工作的一部分，对手册进行了检查和改进。
  4. 内容是开放的。
  5. 内容与我们其余的流程集成在一起。
  6. 另请参见使用手册的一些优势。

如果确实需要演示文稿，则默认使用屏幕截图和手册链接，而不是复制和粘贴内容：

  1. 由于不需要重新格式化，因此速度更快
  2. 它使人们习惯了手册的格式

  3. 它确认它已经在手册中

    值得

    另一家公司询问我们如何使用该手册，因为在他们的公司中，该手册无法正常工作：“在很多情况下，知识库中记录了某些内容，但人们对此一无所知，因为他们从不费心去阅读或阅读。搜索。有些人对他们认为的“文字墙”非常反感。”
    为了确保人们花时间在阅读手册上，我们应该遵循上面的“手册指南”，并且：

  4. 遵循写作风格指南

  5. 具有出色的搜索功能（我们使用Algolia），并且将其公开，因此您可以Google搜索
  6. 在入职期间测试人们的知识
  7. 给出真实的例子
  8. 避免公司说话，描述类似与朋友交谈的内容

    Wiki手册无法扩展

    公司手册经常以Wiki开始。与使用GitLab合并请求和GitLab页面的静态网站相比，这种格式使人们更容易工作。但是，随着时间的流逝，Wiki往往会过时，因为它们的组织方式很差并且过时。
    在Wiki中，不可能提出涉及页面的多个部分和/或多个页面的建议。因此，很难重新组织手册。由于GitLab合并请求和GitLab页面基于分布式版本控制，因此您可以划分提交者和批准者的角色。这样可以进行分工，使手册保持最新状态：
  • 可以阅读该手册的任何人都可以提出建议
  • 领导人（往往时间紧迫）只需要批准这样的提议

Wiki也不鼓励在变更方面进行协作，因为没有办法像合并请求那样讨论提议的变更。

手册的外部使用

请记住，就像我们所做的几乎所有事情一样，我们的手册是开源的，并且我们希望其他公司可以将其作为自己文档和实践的灵感。就是说，手册应该始终具体针对我们的工作，而不是我们想要成为的人，并且随着时间的推移，每个公司都需要填写自己的手册。

受到GitLab的启发

如果您的公司受到GitLab手册的启发，我们很想知道是什么启发了您。请参阅我们的GitLab启发页面。

搜索手册

每个GitLab手册页面在页面顶部附近都有一个搜索字段。一些网络浏览器和生产力工具可让您集成自定义搜索引擎，包括GitLab手册搜索引擎。

谷歌浏览器

如果您使用的是Google Chrome浏览器，则可以在大约一分钟内将GitLab手册搜索添加到地址栏中。

设定

  1. 打开Chrome的搜索引擎设置。您可以浏览Chrome>偏好设置…>搜索引擎>管理搜索引擎，也可以直接加载chrome：// settings / searchEngines。
  2. 点击“其他搜索引擎”旁边的“添加”按钮。
  3. 在“搜索引擎”字段中输入类似“ GitLab手册”的内容。
  4. 在“关键字”字段中输入“ handbook”或“ hb”之类的内容。
  5. 将https://about.gitlab.com/handbook/#stq=%s&stp=1其复制并粘贴到“使用％s代替查询的URL”字段中。

  6. 点击“添加”按钮。

    用法

  7. 通过单击，点击或⌘-L在macOS或Ctrl+LLinux 上按来选择Chrome的地址栏。

  8. 输入您输入的任何关键字（例如“手册”或“ hb”），Chrome浏览器建议您在地址栏的右侧“按Tab来搜索GitLab手册”（如果使用的名称则类似）而非“ GitLab手册”）。
  9. 按Tab键，您的地址栏应更改为指示它将搜索GitLab手册。
  10. 照常搜索。请注意，这将直接使用手册的搜索引擎而不是 Google进行搜索。