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

本文为《社区使用指南系列》学习笔记,关于撰写一篇 Wiki 文章,很多人认为是一件很简单的事情,随便从文档或者 Google 中复制黏贴进来,就是一篇 Wiki。

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

attachments-2019-10-nlp7ItsI5db8daa9b4c58.png

1. 如何定义高品质?

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

  • 1. 写好开头 > 文章最开始的地方是最重要的,好的开头应该能快速让读者身临其境,最好是由一个问题,或者一个设想中的案例引起全文。
  • 2. 示例代码 >大部分的 Wiki 文章需要代码演示,代码示例越多、越实用,读者就会更好理解。另外代码还需配带输出内容,这会使代码看起来更加直观。代码示例应该是撰写 Wiki 时设计的重点。
  • 3. 经验分享 > 编程经验分享,这些是 含金量 最高的,也与文档区分开。分享的经验,可以是过往编程的经验,也可以是通过阅读大量文章并总结、亲自测试过的经验。
  • 4. 最佳实践 > 以传播更好的编程实践为目的,我们应该让新手在学习 Wiki 时养成一些 编程好习惯,例如 APDL 中函数允许传参数组,但是这种做法会降低代码的可读性,撰写 Wiki 时就应加入提醒:「实际开发中,我们应该避免这么做。并且附上理由」。最佳实践也可以从大量的文章阅读中获取到。

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

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

2. 参考

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

  • 发表于 2019-10-30 09:55
  • 阅读 ( 116 )

[版权声明] :本文文字、代码及图片版权归原作者所有,任何媒体、网站或个人未经本网协议授权不得采集、整理、转载或以其他方式复制发表。已经本站协议授权的媒体、网站,在使用时必须注明“稿件来源:学研谷”。

0 条评论

请先 登录 后评论
猜猜我是谁
XY

156
提问
268
回答
57
文章
邀请回答推广