文件如何处理第三方和双重来源的内容

作者: Zach Corleissen,云原生计算基金会

编者注:Zach是Kubernetes文档特别兴趣小组(SIG Docs)的主席之一。

去年夏末,SIG文档开始了有关Kubernetes文档中第三方内容的社区对话。这次谈话变成了 Kubernetes增强建议 (KEP),经过五个月的审查和评论,SIG Architecture批准了KEP为 内容指南 Kubernetes文档。

Kubernetes文档现在处理第三方内容的方式如下:

始终允许链接到Kubernetes项目(kubernetes和kubernetes-sigs GitHub orgs中的项目)中的活动内容。

Kubernetes需要一些第三方内容才能发挥作用。示例包括容器运行时(容器,CRI-O,Docker),网络策略(CNI插件),入口控制器和日志记录。

如果Kubernetes必须运行,则文档可以链接到Kubernetes项目外部的第三方开源软件(OSS)。

这些常识性指南可确保Kubernetes文档记录Kubernetes。

保持文档集中

我们的目标是让Kubernetes文档成为Kubernetes功能的可靠指南。为了实现这一目标,SIG Docs是 追踪第三方内容 并删除所有不在Kubernetes项目中的第三方内容 Kubernetes正常运行所必需的。

重新定位内容

某些内容将被删除,读者可能会发现有帮助。为了确保读者可以持续访问信息,我们在此之前向利益相关者提供 1.19发布文档的截止日期, 2020年7月9日 重新安置计划删除的任何内容。

在接下来的几个月中,随着贡献者打开PR来删除内容,您将在文档中看到更少的第三方内容。

背景

随着时间的推移,SIG Docs发现文档中供应商的内容在增加。一些内容采用了特定于供应商的实现形式,而Kubernetes不需要在项目中运行。其他内容是伪装的广告,内容很少或没有。一些供应商的内容是新的。其他内容已经存在于文档中多年了。显然,文档需要明确,明确的准则,以规定允许和不允许的第三方内容类型。的 内容指南 从社区进行审查和评论的漫长时期出现。

当文档准确,有用,值得信赖且始终专注于功能时,它们才能发挥最佳性能。根据我们的经验,供应商的内容会削弱信任度和准确性。

简而言之:功能文档不是供应商宣传其产品的地方。我们的内容政策使文档始终专注于帮助开发人员和集群管理员,而不是市场营销。

双重来源的内容

影响较小但也很重要的是Kubernetes文档的处理方式 双重来源的内容。双源内容是在多个位置或从非规范来源发布的内容。

来自 Kubernetes内容指南:

Kubernetes文档将尽可能链接到规范的资源,而不是托管双重来源的内容。

最小化双重来源的内容可简化文档,并使Web上的内容更易于搜索。我们也在努力在Kubernetes文档中整合和重定向双重来源的内容。

贡献方式

我们正在跟踪第三方内容 Kubernetes网站存储库中的问题。如果您发现第三方内容超出了项目范围并且不是Kubernetes正常运行所必需的,请对跟踪问题发表评论。

识别出不合格内容后,即可随意打开PR!

想知道更多?

有关更多信息,请阅读以下内容的问题描述: 追踪第三方内容.