第04课: wiki 在 GitHub

Git -> wiki

GitHub 是基于 Git 的社交平台, 当然的,每个仓库的维基( GitHub-wiki ) 也是能通过 Git 来远程维护的, 怎么来?

什么人可以用 wiki ?

~ wiki 不是任何人都可以用的!

挖掘自 101026 老糟

前述功能没有用过,必然是:

断言

任何 wiki 不好用的理由
都仅仅理由,e.g:
    word 经验是即得的不用学习
    wiki 无法快速使用表格
    wiki 难以排版不好看

笔者曾经在各种公司/社区中尝试推广过维基, (当然,那时是基于 MoinMoin )

多年后,才醒悟以往的努力都使错方向了:

  • 维基的本质是相互服务,文章共用
  • 而所有不习惯维基的人,都不是维基用户
  • 只是文章消费者,本质期望是:
    • 有人为他们准备好 清晰/明了/排版漂亮 的索引页面
    • 他们随时可以查阅想查阅的!

怪不得一理解维基是要自己编辑的,第一反应当然是不能用!

没有分享的冲动,没有结构化知识,还想有专人为您服务?!

  • 对分享人不公平!
    • 屈从你的格式/分类?!
  • 对其它查阅者也不公平!
    • 屈从你的标题/结构?

所以,最核心的问题是:

启用 wiki 
一定要事先定位明确
  • 原先推广维基时,首先都是尝试说明什么是维基,而不是怎么使用……
  • 但是,真的是在 Office 淫威之下的人们,大多数无法想象 Word 不方便之处(也可能是拒绝想象)
  • 但是,维基也的确是可以当成各种平台来用:
    • 有公司用维基作工单系统
    • 配合插件,可以作个人/团队 blog
    • 共同写作平台
    • FAQ
    • ……

维基是真正作到本身简单到极致,使用正式自由到充分的信息管理平台了, 就象 Scrunm 成功实施的团队一样,人最重要! 使用维基成功,必须是:

  • 团队有知识积累的冲动
  • 所有人有知识分享的冲动
  • 所有人有时间记录知识片段
  • 所有人愿意配合其它人整理知识体系
  • ……

那么: 是作为随手分享的知识经验库还是作为正式的文档资料库?

从一开始就一定要搞清楚!

  • 如果定位是后者,那要想保证 wiki 文档的权威性,就不能把其他分享掺合进来,就一定全是正式文档。
  • 这里如何组织文档是非常重要的问题:
    • wiki 的 url 太灵活了,这虽然方便,但其实对使用者有了比较高的要求。
    • 别说非技术人员,就是技术人员在 “我的文档该放在哪儿” 这个问题上也是有些纠结的
    • 这一点是将 wiki 作为正式文档库的核心障碍
    • 如果就这一点多下些功夫,制定方便的规范和流程并且给出培训,就好很多
  • 这时,wiki 可以基本取代非流转性的(无需流转到客户手中)word文档
    • 如果需要流转,导出就行了。
    • 但电子表格和幻灯是完全没法的。
      • 但这两种文档一般也没有相互链接,自由索引/复用,统一搜索等需求。
      • 建议电子表格类文档不要往 wiki 里整了
      • 如果统一存在仓库中,引用时给出 url ,或者直接上传复件,如果要显示局部数据,给出截图。
      • 当然,有心用外部工具将 excel 转化为 md/html 格式表格,再嵌入到文档中也是好的

wiki 本质是什么?

聪明的偷懒

  • 1995 WikiWikiWeb 发布标志 Wiki 这一全新的信息组织形式的创立
  • 而其基本动力只是欧洲几个实验室的化学家偷懒
  • 不愿意用邮件反复传送一个文章的版本
  • 所以,发布了一个没有内容管理后台的直接由文章自身组织的网站
  • 任何有权限的人,都可以即时编辑任何一页的内容
  • 然后,维基百科 将这种偷懒方式变成了改变人类知识积累形式的开创性全网实验,并成功了!

那将知识/信息/数据/……在一个 GitHub 仓库中的管理来考虑:

为什么有 GitHub-wiki ?
  • Repository (以下简称 repo. )仓库追踪持续变化的代码 -> 为了构建出可用作品
  • Issue 追踪过程中识别出来的问题/任务/想法/方案 -> 最终要落实到 repo. 的代码
  • 那么,在所有过程中,团队逐步发明/发现/约定 的代码/作品/ Issue 之外的知识在哪儿管理?
    • 是的,必然是个 wiki (维基)
    • 也只能是个 wiki 才能足够 wikiwiki 的跟上 GitHub 中如此高速的迭代
    • ( wikiwiki 夏威夷语 ~ 赶快)
  • 所以,GitHub-wiki 中应该维护什么内容?
    • 自然的,和仓库内容相关的
    • 持续积累的关键知识点
    • 所有成功/规范的开源作品仓库中
    • GitHub-wiki 几乎都约好了一样放置并维护了:
      • 整体介绍
      • 如何在 linux/mac/win 环境中安装/使用/调试 的手册
      • FAQ
      • 许可证说明
      • 如何加入社区贡献渠道
      • ……
      • 基本上就是一个标准的 Apache 基金会项目网站的传统内容

GitHub-wiki 的最佳实践?

~ GitHub 协作五大业余姿势 | ishanshan's blog

  • 第一时间给出 _Footer.md+_Sidebar.md
  • 并索引第一时间发布的框架性文章包含:
    • 第一时间给出 wiki 命名准则
    • 第一时间给出核心的文档树
    • 第一时间给出 wiki 文章模板
    • ……
  • 坚持用靠谱的 md 编辑器在本地定心编辑高品质的文章再 push 到 GitHub
    • 是的,Git 的使用有非常严正的仪式感
    • 可以从一开始有效杜绝随意的文章编辑行为
  • 死也不用中文文件名:
    • 整个 GitHub 体系中只有两处可以创造有意义的 URI
    • repo. 中的文件名
    • GitHub-wiki 中的文章
    • 前者受制代码预览的功能限制,很难有正式文章的感觉
    • 后者是可以安心传播/分享的有效文档的发布链接
    • 所以,使用中文文件名本质就是对互联网大吼:
      • 俺就是不想让你们看这个文章……
  • 以及其它只有认真用起来 GitHub-wiki 才知道的技巧

提问

~ 是的,GitQ 不是单向灌输,双向交流才真诚

  • GitHub-wiki 包含的功能中哪个你最喜欢?为什么?
  • GitHub-wiki 的形式,还能拿来作什么?
  • 如果你来增强 GitHub-wiki ,最想要的那个功能是什么?

欢迎大家来我的读者圈评论作答或提问交流 ~

评论将由博主筛选后显示,对所有人可见 | 还能输入1000个字符 “速评一下”
©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页