感谢你在开发者社区中分享你的专业知识和洞察。

freeCodeCamp 专栏将帮助你启发并鼓励全世界的开发者、设计师和数据科学家等专业人才。

freeCodeCamp.org 是访问量最大的技术网站之一,成千上万的读者将在这里通过阅读你的文章而受益。

我们的社交媒体账号拥有很高的关注度,网站的可访问性和 SEO 效果都做得十分出色,同时,我们提供的学习资源严谨而优质,在业内深受认可——这些优势都将为你的文章吸引更多读者。

在这篇写作指南中,我们将提供一些指导建议,帮助你优化自己的文章,扩大影响力。

(需要说明的是,我们稍后会对中文版专栏进行优化,比如增加标签和搜索框,可以参考英文版专栏。)

请不要把 freeCodeCamp 专栏当作一个发布“日常博客”或意识流似的观察性作文的平台。

内容至上,请在你的文章里展示事实、引言、代码片段和可视化数据等等优质内容。

大量数据表明,文章越深入,人们会花越长的时间阅读它,并且越有可能与朋友分享。

如果你围绕某个主题写出的文章少于 1,000 字,请先尝试对其进行更多研究。通过深入并拓展研究,你可以向读者传递更多洞察。

人们很忙,所以你必须立即吸引他们的注意。

标题需要有吸引力

在开始撰写正文部分之前,你需要花点时间构思一个吸引眼球的标题。然后,你的整篇文章将围绕标题发散与聚拢,以作支撑。

我们发现了两类可作为典范的文章:深度技术文章个人叙述文章

比如,深度技术文章可以采用这样的标题:

  • "How to fix…"/《如何修复......》
  • "How to build…"/《如何构建......》
  • “How to [task] with [tool]”/《如何 [采用什么工具] 来 [完成什么任务]》
  • "How [something] works"/《如何实现 [XX] 》
  • "The [adjective] guide to…"/《关于 [XX] 的 [深度、高效、完整等等形容词] 指南》
  • “What is a [noun]. In English, please.”/《什么是 [XX] 》
  • “What exactly is [noun]?”/《[XX] 究竟是什么》
  • “Why [something] matters.”/《为什么说 [XX] 很重要》
  • “Learn [something] in N hours”/《如何在 N 小时内学会 [XX]》
  • "A history of [something]”/《[XX] 历史解读》
  • “The story behind [something]”/《[XX] 背后的故事》

而个人叙述文章可以采用这些标题:

  • "How I [did something]"/《我是如何 [做 XX 的]》
  • “I [did something]. Here’s what I learned.”/《我从 [做 XX] 中学到了这些经验》
  • “How I went from [something] to [something] in N years”/《我是如何在 N 年之内从一个 [XX] 成为一个 [XX] 的》
  • “Why I started [something]”/《我为什么要 [做 XX]》
  • “I’ll never [something] again. Here’s why.”/《我为什么不会再 [做 XX]》
  • “How I [did something] without [something]”/《在没有 [XX] 的情况下我是如何 [做 XX] 的》

添加封面图片

在你确定了一个清晰的有信息量的标题之后,添加一张合适的封面图片,然后点击右上角的发布按钮。

一些作者为自己的文章设计封面图片。你可以在一些免费网站设计图片,比如 https://www.canva.cn/。我们可能在 Facebook 或 Twitter 分享你的文章,所以请注意图像宽高比应为 1.91:1,以免分享时图片不能完整显示。

如果你没有合适的封面图片,可以单击左下角的 Unsplash 按钮添加 Creative Commons Zero 图片(无需注明来源)。

设置 URL

你可以直接设置文章的URL。我们建议你使用简短的描述性的 URL,比如“machine-learning-with-pytorch-tutorial” 或 “from-trucker-to-developer”。对,使用英文而不是拼音。

设置好 URL 并发布文章之后,请不要更改 URL,因为有可能我们在别处推荐了你的文章,URL 变了的话就会导致 404 错误。

添加标签

为你的文章选择一到五个标签。当你键入一些关键词时,下拉列表会出现标签提示,从中选择即可(中文版标签即将上线)。

读者很容易通过搜索和浏览标签来找到你的文章(中文版搜索功能即将上线)。

你选择的第一个标签是最重要的,它会显示在你的文章上方,如下所示:

标签以下的部分是默认设置,请不要改动。

如何写出人们乐于阅读的文章

重视语法,拼写和格式

条理严谨且格式清晰的文章阅读起来令人愉悦。以下建议可以帮助提高你的文章的可读性:

  • 简单化:尽可能使用简单直接的语句。
  • 使用短句:将长句分解为短句,这有助于人们更快地阅读并更好地理解。
  • 使用短段落:将较长的段落分解为一两句的段落。如果你的文章有好多长段落,读者可能放弃阅读或只是略读。
  • 检查标点符号:太多感叹号可能会分散注意力!少用分号;只需使用句号。省略号......好吧......看起来有点累赘。
  • 使用小标题让文章结构更清晰:你可以在编辑器中选择设置大标题、子标题。
  • 尽量少使用缩写:有的缩写并不是所有人(特别是初学者)都知道,比如,LGTM(look good to me),e.g.(例如),js(JavaScript),所以少使用缩写吧。
  • 特别注意全角/半角文字内容和标点符号的用法,比如,全角文字和半角文字之间需要加空格(为下列项目添加 CSS 属性)。

反复校对

有些作者写得很快,他们可以一边思考一边将自己的想法写下来。有些作者会在做好所有研究之后才开始写作。

无论你习惯什么样的写作过程,请在写好之后跳出作者思维,从一个陌生的读者的视角来阅读你的文章。

反复阅读,甚至可以读出声来。然后你会惊讶地发现其中有一些标点错误、用词错误或者不通顺的语句。

在代码中添加语法高亮显示

你可以通过键入三个反引号(```),然后按空格键,来创建代码块。

你甚至可以指定要进行语法突出显示的编程语言,例如,输入```js 将高亮显示 JavaScript 语法。我们还支持其他常用的十几种编程语言的语法高亮显示。

紧扣主题

读者的时间是宝贵的。尽量让你的文章值得他们从忙碌的生活中抽出来阅读,也就是说帮助他们尽可能多地从你的文章中获取价值。

尽可能按照这个步骤来撰写深度技术文章:

1、写一个简明介绍,告诉读者他们将从这篇文章看到什么

2、使用像这样的编号列表来展示步骤

3、尽可能详细阐述

4、最后提醒读者他们看了什么内容

将你自己的故事写得像一篇引人入胜的小说

即使你的标题可能会泄露你的故事结尾,比如,《我是如何在两年内从一名卡车司机转型成为一名软件开发者的》,你仍然可以像写小说一样写这篇文章。

相比根据时间顺序从头到尾地叙述你转型的故事,你可以在文章开头描写转型之前和之后你的生活有何不同。

试试围绕中心冲突来构思故事,例如,你在转型过程中克服了:

  • 移民的困难
  • 残酷的求职面试
  • 学习障碍
  • 年龄歧视
  • 或者,拖延症(最常见的挑战)

冲突是叙事的核心。书籍和电影很有趣,因为角色之间、角色所处的环境之间甚至是角色自身存在冲突。

写一篇完整的长文,而不是把长文分为多篇短文

我们从长期的观察中发现,如果人们没有阅读一个系列文章的前面部分的话,那么他们没有什么耐心阅读其中的第二、第三或第 n 部分。

与此同时,我们发现那些非常长的、有深度的文章却能收到非常好的反响。人们会把你的长文添加书签或在社交媒体上分享,以便他们可以随时回过头来再阅读。

如果一篇文章比较长,通常人们会认为这篇文章是作者认真写的,内容是丰富的。这会鼓励读者放慢脚步,真正花时间阅读你的文章。许多读者甚至会在家里打开他们的代码编辑器,边阅读边写代码。

文章内容必须符合规定

freeCodeCamp 的学员中既有成年人也有青少年,所以,你在这里发布的文章不得包含黄、赌、毒等不良信息或政治敏感内容,避免文章中出现侮辱性语言。

如果某篇文章违反了 freeCodeCamp 的行为准则,我们会立即将其删除。

关于多平台交叉发布文章的说明

如果你希望有很多人阅读你的文章,那么我们建议你不要在多个平台发布文章,而是专注在一个专栏写作——不管是 freeCodeCamp 的专栏,还是你自己的博客,或是其他线上平台。

你可以将自己之前写的关于某个主题的几篇文章(例如 “Visual Studios 插件”或“高级 Bash 命令”)编辑成一篇较长的文章,在 freeCodeCamp 专栏发布。

文章中是否可以出现推广性质的内容

freeCodeCamp.org 是靠捐款人支持的非营利组织。我们不希望让任何人感觉我们有所谓的“收费策略”(我们完全没有),否则可能会影响人们给我们捐款的意愿。

不过,我们完全理解你可能希望宣传自己的最新书籍、课程、SaaS 应用程序或其他产品。

我们希望你尽可能优雅地做推广,比如,你完全可以在文章末尾用一句话介绍你的产品。

不要在文章开头就放你的产品链接,因为这看起来就是垃圾信息。

另外,请注意,我们不允许注册品牌账号,禁止任何形式的代写。

请不要使用你的作者账号代表尚未获得邀请注册成为 freeCodeCamp 专栏作者的人发布文章。

请注意,对于你自己的站点的 SEO——与大多数热门网站不同——freeCodeCamp 专栏的所有链接都是 rel =“doFollow”,意思是你在文章中链接的每个页面(包括你自己的博客)都会在 Google 排名中获得提升。

我们也正在着力推进 freeCodeCamp.org 的百度 SEO 工作。

正式发布

当你确定你的文章已经准备好分享给读者,你可以将草稿链接发送给 chinese@freecodecamp.org。

我们的编辑团队将尽快帮助你检查、优化文章,然后正式发布。

我们主要会看标题和开头段落是否可以优化,同时也会更正文章中的格式问题或语法错误。

如果我们觉得你的文章要改的内容比较多,我们会告诉你,那么你可以修改之后重新提交。

其他建议

GitHub Markdown

在这里你可以使用 GitHub 风格的 Markdown 撰写文章。

你可以直接将 Markdown 内容粘贴到编辑框中,内容会立即转换为富文本格式。

你也可以在文章中键入 Markdown 语法来指定格式,比如,用#或 ## 编写标题,或者键入*  表示项目符号列表。

轻松嵌入

如果你想嵌入 Twitter、YouTube 的内容,只需单击新行开头的 + 图标,即可从各种嵌入工具中进行选择。

不过,我们鼓励你谨慎嵌入内容,原因有三:

  • 嵌入内容将调用外部服务,可能会使访问速度变慢
  • 开发者社区中很大一部分人存在视力障碍(或完全失明),他们使用屏幕阅读器阅读文章,嵌入内容的可访问性不如文本的可访问性好。
  • 有的读者在移动端阅读文章,嵌入内容可能在移动端无法正常显示。

你可以填写这份表单申请注册成为 freeCodeCamp 专栏作者。

再次感谢你在开发者社区中分享知识

我们希望这份指南能够帮助你撰写更好的文章,一起帮助更多人学习。

Happy coding. Enjoy writing.

-  freeCodeCamp 编辑团队

原文链接:https://www.freecodecamp.org/news/developer-news-style-guide/