10.4. 如何撰写一篇高品质的 Wiki 文章?

未匹配的标注

如何撰写一篇高品质的 Wiki 文章?

说明

撰写一篇 Wiki 文章,是一件很简单的事情,随便从文档或者 Google 中复制黏贴进来,就是一篇 Wiki。

然而,撰写一篇「高品质」的 Wiki 文章,却不是一件容易的事情,我们一起来探讨下。

如何定义高品质?

一篇高品质的社区 Wiki 除去基本的技术信息,还应该具备以下这些特性:

  • 1. 写好开头

    文章最开始的地方是最重要的,好的开头应该能快速让读者身临其境,最好是由一个问题,或者一个设想中的案例引起全文。

  • 2. 示例代码

    大部分的 Wiki 文章需要代码演示,代码示例越多、越实用,读者就会更好理解。另外代码还需配带输出内容,这会使代码看起来更加直观。代码示例应该是撰写 Wiki 时设计的重点。

  • 3. 经验分享

    编程经验分享,这些是 含金量 最高的,也与文档区分开。分享的经验,可以是过往编程的经验,也可以是通过阅读大量文章并总结、亲自测试过的经验。

  • 4. 最佳实践

    以传播更好的编程实践为目的,我们应该让新手在学习 Wiki 时养成一些 编程好习惯,例如 PHP 中函数允许传参数组,但是这种做法会降低代码的可读性,撰写 Wiki 时就应加入提醒:「实际开发中,我们应该避免这么做。并且附上理由」。最佳实践也可以从大量的文章阅读中获取到。

好的 Wiki 文章读起来一气呵成,并且感觉满文都是干货,犹如一个经验老到的编程高手在语重心长的与你分享他枝繁叶茂的知识。

第 1 和 2 也许比较好实现,但是第 3 和 4 却是需要下点功夫才能做到,接下来推荐一个方法。

参考

撰写时,有一个技巧可以推荐给大家,那就是:

站在巨人的肩膀上。

具体来讲就是参考优秀的文献。每一门技术可参考的资源都不一样,但是基本按照以下分类去寻找,都能定位到一些很棒的参考资料:

  1. 官方文档/教程(文档中有用户评论更佳);
  2. 搜索 Stackoverflow 「关于某个 Wiki 话题」,前 10 ~ 20 个问题;
  3. 阅读 Google 搜索「关于某个 Wiki 话题」,前 10 ~ 100 篇文章;
  4. 社区优秀的免费和付费书籍(如果有的话);
  5. 优秀的出版书籍(如果有的话)。

撰写一篇 Wiki 文章时,先阅读这些资料,能为我们带来很多灵感。有时甚至能来勾起我们追忆过往经验,这样写起文章来就会文思如泉涌。同时,这个「做功课」的过程,对撰写者的学习也有非常棒的助益,因为你会被动地去获取到许多「延伸知识」。

检测清单

以下是一个 Wiki 文章撰写时的检测清单,可以用来自检:

  1. 是否有一个简单易懂的开头?(可以提一个问题,或者场景描述)
  2. 示例代码是否直接易懂?
  3. 示例代码是否都有附带输出?
  4. 是否查阅了相关文档和书籍?
  5. 是否阅读了 Stackoverflow 上相关问题?
  6. 是否阅读了 Google 搜索上相关文章?
  7. 是否还能分享更多的经验和技巧?
  8. 是否有编码「最佳实践」可以分享?

提交 Wiki 前,做到上面列表里的每一项,文章的品质自然不会低。并且随着撰写经验的积累,你会越来越优秀。

结语

撰写 Wiki 的目的是为了学习和总结。如果不给自己提高要求,也不仔细做功课、做调研,那就本末倒置了。

我们的目标绝对不是「完成一篇 Wiki」这么简单,而是:

撰写一篇高品质的 Wiki,并在此过程中职业技能得到提升。

笔者为 LearnKu 的站长,技术涉猎比较广泛,Wiki 功能开发的初衷也是为了巩固个人所学知识。最后,欢迎有兴趣的同学一起参与学习和分享。

参考

本文章首发在 LearnKu.com 网站上。

上一篇 下一篇
讨论数量: 0
发起讨论 只看当前版本


暂无话题~