关于 Wiki、README 和 Markdown

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

若要支持你的团队或项目参与者,请使用 Markdown 向团队项目添加丰富的格式、表格和图像。 可以在团队项目 Wiki 中使用 Markdown 格式、添加到仪表板的内容、团队项目自述文件或其他存储库自述文件。

Wiki

使用团队项目 Wiki 与其他团队成员共享信息。 从头开始预配 Wiki 时,新的 Git 存储库将存储 Markdown 文件、图像、附件和页面序列。 此 Wiki 支持对其内容和结构进行协作编辑。

将现有 Git 存储库发布到 Wiki

许多团队使用 Markdown 记录其代码,并连同代码一起签入这些文件。 虽然 Git 支持维护和审查此类文档以及标准拉取请求,但此类文件对内容的使用者提出了一些挑战。

  • 读者必须经常筛选多个文件和文件夹才能找到感兴趣的内容。
  • 内容缺少组织和结构。 没有固有的页面层次结构来支持读者。
  • 不支持内容版本控制。
  • 搜索内容依赖于搜索代码,而不是针对搜索内容优化的搜索体验。

使用发布代码作为 Wiki 功能,可以将团队项目中定义的一个或多个 Git 存储库发布到 Wiki。 此功能提供了一种将内容与代码库一起维护的方法,并让你有选择地将内容发布到 Wiki 并对其进行更新。

管理为团队项目预配的 Wiki 内容与从 Git 存储库发布的 Wiki 页面的方式之间存在显著差异。 有关详细信息,请参阅 将 Git 存储库发布到 Wiki

Markdown

Markdown 可以轻松地设置文本格式并包括图像。 还可以链接到项目页面、自述文件、仪表板和拉取请求中的文档。 可以使用 Markdown 在以下位置向团队提供指导:

有关支持的语法,请参阅 在 Azure DevOps 中使用 Markdown。

自述文件

可以为每个存储库或团队项目定义自述文件或多个文件。 在 Markdown 中编写自述文件,而不是纯文本。

使用 READM 页面引导参与者在项目中工作。 请考虑添加以下指南:

  • 项目焦点
  • 先决条件
  • 设置环境
  • 有关在项目中完成操作的提示
  • 特定文件的用途或使用
  • 特定于项目的术语和首字母缩略词
  • 有关提交或上传更改和添加分支的工作流指南
  • 项目发起人或联系人

下面是一些伟大的 README,使用这些格式,并向所有受众发表演讲,以获取参考和灵感: