Jupyter 社区传播渠道贡献指南:博客、新闻通讯与网站的全流程协作规范
Jupyter 社区传播渠道贡献指南:博客、新闻通讯与网站的全流程协作规范
Jupyter 项目(本仓库 jupyter/jupyter 是官方元包与文档仓库)除了代码与文档,还有一套覆盖博客、新闻通讯、官方网站的社区传播体系。本文档以 docs/source/contributing/communication-contributions.rst 为核心,系统讲解这三条渠道的投稿/贡献流程、写作规范、评审与发布机制,以及已发布内容的维护规则;结合仓库内社区文档与贡献指南,为你呈现一套可落地执行的"社区传播贡献操作手册"。读完本文,你将清楚一篇博客文章从灵感到发布的全链路、新闻通讯的投稿要点,以及如何通过 Pull Request 为官方网站贡献内容。
一、这份指南在仓库中的定位
communication-contributions.rst 是 Jupyter 官方贡献文档体系中的正式章节,它与开发者贡献指南、文档贡献指南并列,统一收纳在 content-contributor.rst 的目录树(toctree)中,面向所有希望以"写作与传播"方式参与 Jupyter 的贡献者。
从仓库结构可以看出 Jupyter 对社区传播的重视:
- start-contributing.rst 介绍新手如何选择贡献方向,其中明确列出"参与社区(participating in the community)"是与改进代码、改进文档并列的三大贡献方式之一,并推荐从社区指南入手了解沟通渠道;
- content-contributor.rst 说明:作为贡献者,如果需要使用 Jupyter 托管的账号(例如写博客文章、更新网站信息),应向安全小组申请访问权限;
- 本文档则具体拆解博客、新闻通讯、网站三条渠道的"游戏规则"。
需要注意,本指南聚焦的是内容与流程规范,而非代码实现——它解决的是"社区内容从哪来、如何审、如何发、如何改"的协作问题,与仓库的代码贡献(见 dev-contributions 索引)形成互补。
二、博客(Blog):从灵感到发布的全流程
Jupyter 通过官方博客向社区发布技术文章、项目更新与活动信息。博客欢迎社区成员投稿,也欢迎以**客座博主(guest blogger)**身份参与写作——如果你有写作意愿,可以联系团队,对方会指导你完成从选题到成文的全过程。
2.1 技术概览:博客运行在什么平台上
Jupyter 博客运行在 Ghost 博客平台上。选择 Ghost 的原因在指南中有明确说明:为贡献者提供足够的灵活性(contributor flexibility),同时保持易用性(ease of use)。这意味着客座作者可以通过浏览器直接编辑、拖拽图片、撰写草稿,而不必接触代码仓库,大幅降低了投稿门槛。
2.2 核心工作流程:七个关键步骤
从"灵感"到"已发布文章",指南给出了明确的流程骨架:
- 产生写作灵感(be inspired to write a post);
- 在 Jupyter 邮件列表上联系团队,申请博客作者账号;
- 创建草稿(draft);
- 草稿评审(draft review);
- 编辑接受(editorial acceptance);
- 发布文章(publishing);
- (如有需要)更新已发布文章(update)。
下面逐一展开每步的实操要点。
2.3 创建草稿:标题与元数据(Title and Metadata)
草稿阶段的第一个硬性要求是始终在元数据字段中为文章填写标题(title)和规范链接(canonical URL)。
关于 canonical URL 有两个要点:
- 日期可以放进 URL:尤其适用于会重复举办的事件,例如
jupyter-day这类活动可能一年举办多次,事件的实际日期与博客发布文章的日期可以不同,因此把事件日期写进 URL 可以避免同题文章冲突; - 发布后绝不修改:指南用加粗强调了"never change the post's title or the url"。原因非常实际——一旦文章发布,推文、RSS 订阅源等已经引用了既有 URL,任何标题或链接的变动都会导致这些引用失效;部分平台会立即缓存 URL,修改标题会让访客直接进入 404 页面。
实践建议:标题与元数据可以在正文写完后继续打磨,但一旦发布即冻结。作为客座作者,你通常无需操心元数据——编辑或管理员会负责核对与填写。
2.4 创建草稿:图片处理的两条铁律
指南对博客图片给出非常具体的操作规范:
- 不要链接外部图片:外部图片可能被修改甚至下线,一旦图片源失效,整篇文章就会出现破图。正确做法是在编辑器视图中插入
![](),然后把图片从桌面直接拖拽到预览区新建的字段中; - 拖拽上传的图片与博客共用同一 CDN(内容分发网络):图片由博客自身的 CDN 提供,能为读者带来最稳定的加载体验。
此外,文章顶部看到的**精选图片(featured image)**与正文内嵌图片机制不同:
- 精选图片是在元数据字段中设置的,而不是通过
![]()插入; - 许多 feed 阅读器(尤其是移动端)对精选图片和正文图片的处理方式不同;
- 精选图片的独立加载机制允许网络较慢的用户先读到正文内容,而不是等待大图渲染完成——这是体验上的显著优化。
2.5 创建草稿:链接规范
- 尽量避免使用短链接(minified links):短链接的多重重定向会明显降低移动端浏览体验;
- 如果你确实需要统计页面浏览量,指南明确说明这项数据由 Google Analytics 负责跟踪,不需要借助短链接服务来获得统计能力。
2.6 草稿评审(Draft Review)
当你自认为文章已经完成,请找另一个人通读全文,并核对所有发布前可能遗漏的参数与细节。指南特别强调协作心态:
"你并非孤军奋战,这是团队协作,我们在这里帮助你。如果草草了事,你花在修复错误上的时间很可能比一开始就做对要多得多。"
这体现了 Jupyter 社区对内容质量的一致要求:评审不是走形式,而是防止"赶工后返工"的关键环节。
2.7 编辑接受与发布(Editorial Acceptance & Publishing)
发布动作通常由编辑或管理员完成。他们的职责是对文章做最终质量检查:
- 核对所有元数据是否正确填写;
- 确认没有使用外部图片;
- 复查前面描述的所有质量检查项。
一切就绪后,只需将文章设为公开可见即可完成发布。这里可以看到 Jupyter 博客"投稿人写内容、编辑把关质量"的分工模型:客座作者无需拥有任何平台管理权限,降低了参与门槛。
2.8 修改已发布文章:克制且留痕
博客订阅者每次更新都会收到通知,因此指南要求"更新与修复要节制(parsimoniously)"。具体规则:
- 小问题(如错别字)可以等几个小时再修,不必立即改动引发通知轰炸;
- 实质性更新(如地点、时间变更)时,在文章顶部(或底部,视重要程度而定)插入
[Update]段,注明更新的日期/时间; - 正文中的错误信息不要直接替换删除:指南建议用**删除线(strike-through)**标记为过时内容,而不是抹去原文。这样当读者面对多个来源给出不同信息时,能清楚地判断哪条信息是准确、更新过的。
三、新闻通讯(Newsletter):把更新送达订阅者
3.1 概览
Jupyter 会周期性发布新闻通讯,向社区同步重要更新、事件、版本发布和其他相关信息,通常通过邮件发送并同步发布在官方网站上。它是博客之外另一条"主动触达"社区的信息通道。
3.2 如何投稿
如果你有希望与更广泛的 Jupyter 社区分享的公告、活动或更新,可以提交内容进入下一期新闻通讯:直接通过邮件把拟发布的内容发送给核心团队即可。与博客的"申请作者账号"模式不同,新闻通讯采用内容投稿制——由团队审核并编排入刊。
3.3 内容指南(Content Guidelines)
指南给出了四条简洁明确的内容要求:
- 投稿内容简短、清晰、切题(Keep submissions brief, clear, and to the point);
- 包含相关日期、链接和联系方式;
- 语法规范,尽量少用行话(jargon);
- 如果附上图片或 Logo,必须同时提供替代文本描述(alt-text)——这是无障碍访问(accessibility)的基本要求,也便于订阅者与屏幕阅读器用户理解内容。
3.4 排期与归档
- 发布频率:新闻通讯通常按月或按季度发布(monthly or quarterly);
- 归档:历史各期会归档在 Jupyter 官方网站上,后续通讯中也可能会引用往期内容作为参考。
四、官方网站(Website):以代码方式贡献内容
4.1 概览
官方网站(jupyter.org)是访问项目信息、文档、下载资源和社区资源的主要门户,涵盖 Jupyter 生态全景、JupyterLab / Jupyter Notebook 等核心项目入口、教程与入门指南、社区与贡献者信息等。
4.2 贡献方式:标准的开源协作流程
与博客、新闻通讯不同,网站内容的贡献走的是代码仓库 + Pull Request 的流程。如果你发现官网有拼写错误、失效链接,或想改进内容,可以:
- Fork 该仓库;
- 修改内容;
- 提交 Pull Request。
网站贡献与其他文档走相同的评审流程,且必须遵循项目的风格与语气(style and tone)。这一点与仓库内 docs-contributions 文档指南 所强调的规范一致——内容质量与格式统一是合并的前提。新手可以参照 start-contributing.rst 中"Web Development"一节,了解官网仓库的开发者安装与本地测试方式(quick local testing),在提交前先本地验证改动。
4.3 托管与部署
- 官网部署在 GitHub Pages 上;
- 当改动合并进仓库主分支后,站点会自动更新(updates automatically when changes are merged into the main branch);
- 因此指南明确要求:提交评审之前,务必先在本地测试你的改动。
这条"合并即部署"的机制意味着任何一次合入主分支的改动都会立即影响线上站点,本地测试因此是强制性的质量门槛,而不是可选项。
五、仓库中的相关配套资源
要完整落地这套传播贡献流程,本仓库还提供了若干配套文档,建议组合阅读:
| 资源 | 位置 | 用途 |
|---|---|---|
| 贡献总览 | content-contributor.rst | 说明传播贡献在整体贡献体系中的位置,以及申请 Jupyter 托管账号(写博客、更新网站)的入口(联系安全小组或提交 issue) |
| 新手起点 | start-contributing.rst | 列出社区参与方式与官网仓库的开发安装指引 |
| 社区指南 | content-community.rst | 汇总社区论坛、博客、新闻通讯、网站、Zulip、邮件列表等全部官方沟通渠道的入口与定位 |
| 会议主办指南 | host-guide.md | 社区会议的实操范本:会前如何写会议公告博客(含草稿模板、媒体策略工作组评审、多渠道发布)、会后如何把会议记录归档进 community-call-notes |
| 文档构建配置 | conf.py | 本仓库文档站的技术底座:Sphinx + pydata_sphinx_theme,含自定义样式、站点统计(Plausible)等 |
尤其值得留意的是 host-guide.md:它把本文档的博客流程落到了具体场景——发布社区会议公告时,需要在博客平台撰写文章、提交媒体策略工作组(JMS)评审、并在社区论坛等公共渠道同步宣传,会后还要把会议记录以 Markdown 文件形式提交到 docs/source/community/community-call-notes/ 目录并更新其 index.rst 目录项。这印证了"博客 + 网站 + 新闻通讯"三条渠道在实际社区运营中是协同运转的。
六、核心规范速查表
最后,把本文档的关键规则汇总为一张速查表,便于写作与评审时对照自查:
| 渠道 | 关键规则 |
|---|---|
| 博客 · 元数据 | 必须有标题与 canonical URL;事件类文章可在 URL 中放日期;发布后绝不改标题或 URL(否则破坏推文/RSS 链接并导致 404) |
| 博客 · 图片 | 不链接外部图片;用 ![]() + 拖拽上传,由博客 CDN 托管;精选图片经元数据设置,便于移动端与慢网络读者 |
| 博客 · 链接 | 避免短链接(多重重定向伤移动体验);统计由 Google Analytics 承担 |
| 博客 · 评审 | 发布前请他人复查;发布由编辑/管理员完成并核验元数据与图片来源 |
| 博客 · 更新 | 小错可稍后修;实质更新用 [Update] 段注明时间;过时信息用删除线标记而非删除 |
| 新闻通讯 | 邮件投稿给核心团队;内容简短清晰、含日期/链接/联系方式、少用行话、图片附 alt-text;通常月更或季更并归档于官网 |
| 网站 | Fork → 修改 → Pull Request;走统一评审流程并遵循项目风格;部署于 GitHub Pages,合入主分支即自动上线,提交前必须本地测试 |
掌握以上规范,你就能以"写作与传播"的方式正式参与 Jupyter 社区:无论是成为客座博主、向新闻通讯投稿,还是通过 Pull Request 改进官网内容,都有清晰的路径与质量标准可循。完整的原始规范可随时查阅仓库中的 communication-contributions.rst。