如何发表一篇文章

我们讨论在这里发表一篇文章的流程和一些写作建议。

内容

一篇文章通常讨论一个主题。建议长度在控制在读者能够10分钟读完以内。保守估计一个人可以一分钟读200个字,那么总长度应该在2000字内。如果文章里面有图片,表格和代码,我们可以简单估算成一张图片15秒,一行代码和表格2秒,那么一篇文章最多可以有2张图片,5个代码块,每块10行代码,2个表格,每个表格5行,外加一千五百字。这个只是一个很简单的估算。整体来说,一篇文章不应该太长(可以分割成好几篇),也不要太短(坚持技术深度)。

写作的时候一般需要花费十倍的时间。例如10分钟读完的帖子我至少需要花100分钟。所以预留好时间。

开头:Why

我们首先应该解释为什么读者要读这篇文章,而不是去知乎上读一篇类似主题的文章,或者说去微信公众号上看一篇轻松的水文。

举个例子,假设我们下一篇是介绍 Gluon 的新 CV 工具包,那么我们需要说我们为什么要造这个轮子。常见误区是说我们这个轮子快,好用。这个只是关于”这是什么”,而不是”为什么”。我们需要给读者理由让他们说服自己去读这个文章和试用这个工具包。

所以我们可以换一种说法:目前市面上虽然 CV 包很多,但分散在各个地方,而且接口不一致,质量也是良莠不齐。用户需要花费大量时间去尝试。而我们这个工具包将提供state-of-the-art 算法的实现,保证算法之间接口相似,可以重复代码,而且提供质量保证。可以为开发者节省大量时间。

另外的例子可以参考 《动手学深度学习》为什么开设 Apache MXNet 博客

正文:What / How-to

一篇文章要么介绍一个东西,要么讲一个东西怎么做。这个是主体正文。

博客文章和我们平常写的学术论文不一样。论文是正式的清晰介绍想法和技术细节,面向的对象是研究人员,通常他们有更多时间来读论文。有时候甚至为了使得论文看上去更加高级,我们会故意的形式化一些东西。但博客文章相反,面向的对象更多是实践者,他们可能是有兴趣的学生,或者公司的从业者。他们利用业余时间读这些文章,想快速弄懂或者上手某个事情,并不是很有耐心去读各个细节。所以博客文章需要写的简单,好读,用尽可能简单的文字和代码介绍一个东西。文字上也可以更加随意些,可以更加贴近日常说话。不过我们日常说话经常中英文夹杂,建议在写作的时候尽量全使用中文,显得不是那么的随意。

结尾:讨论

我们可以用一两句话来总结,或者省略掉也行。不过一个很重要的事情是我们需要留下一个方式来方便读者问问题和讨论。建议对每一篇文章我们在论坛里创建一个分类是 Blog讨论 的话题,然后在末尾附上链接。我们在之前的动手学深度学习教程里这么做了,效果很好。

流程

我们将文章保存成使用 日期-标题.md 的格式。例如 2018-01-01-hello-world.md. 这里日期不能超过当前日期,否则不会被编译。

然后将 md 文件提交到 https://github.com/mxnet-zh/blog_post 目录下。合并之后前面文章地址将会是 https://zh.mxnet.io/blog/hello-world。

如果想预览草稿,可以使用本地编译。首先安装 Jekyll,和插件

sudo gem install jekyll-paginate jekyll-sitemap

然后进入到 blog 这个文件夹后运行 jekyll serve 后打开 http://localhost:4000 就能预览了。注意任何本地改动会触发重新编译使得我们刷新浏览器可以预览改动。

格式

文章的格式使用的是 markdown。具体来是 kramdown

文章头

头部我们署名标题和作者

---
title: 文章的标题
author: 作者和单位
---

正文

每个章节使用二级章节 ##,因为一级章节留给了标题。

使用图片。我们可以将图片保存在 img/ 下,或者引用网络地址。Kramdown 支持图片缩放,但并没有特别方便的办法来添加题注。

代码 预览
![](https://octodex.
github.com
/images/yaktocat.png)
{:width="300px"}

使用代码

```python
from mxnet import nd
x = nd.zeros((2,3))
```

预览:

from mxnet import nd
x = nd.zeros((2,3))

使用公式

  • 行内公式。代码:$y = \sum_{i=1}^n x_i$,预览 $y = \sum_{i=1}^n x_i$。
  • 整行公式。代码:$$ y = \sum_{i=1}^n x_i $$,预览

    \[y = \sum_{i=1}^n x_i\]

中英文

如果一个英文单词跟非标点中文字符相连,记得中间插入空格。例如,hello 世界。

换行

如果对中文进行换行,会被插入额外的空格。所以建议一个段落就是一行。

链接

链接 前后插入空格也是不错的选择。

使用脚注:

代码 预览
脚注会出现在文末 [^1]
[^1]: 脚注在这里
脚注会出现在文末 [^1]

表格

代码:

什么 | 在 | 干嘛
---- | --- | ---
世界 | 在 | 这里
地球 | 在 | 运动
月球 | 绕 | 着动

预览:

什么 干嘛
世界 这里
地球 运动
月球 着动

CSS 样式

样式模板是基于 monochrome。这是一个极简的样式,适合纯文字。我们对其进行了一定的修改,修改的样式放在 _sass/custom.scss 里。

讨论点这里