技术文章撰写&发布指引

技术文章的价值

TiDB 社区是由 TiDB 生态中的开发者、用户、Contributor、合作伙伴一起建立的分享、学习平台

相信你来到这里就是被社区开放和共享的氛围所吸引,在这里我们鼓励任何类型的知识分享,技术文章是重要的分享形式。

作为作者,你需要把已经内化的知识点,经过一层抽象准确地表达出来,写文章的过程也是自我沉淀和总结的过程。同时,还能让更多的社区小伙伴认识你,打造个人影响力。

对于读者来说,你的经验可能刚好是他们在苦苦追寻的答案,予人玫瑰,手有余香,何乐不为!

技术文章的写作过程

可能你已经有写文章的想法,但不知如何下手,下面的思路可以给你参考:

确定选题

首先是确定选题,选择一个你要表达的主题,选题的最终目标是对读者而言有价值。大体上可以划分为以下几种类型:

  • 一是通识型技术选题,选择一个适用性广泛、但切入角度十分具体的主题来进行分享,如果角度合适,此类型选题易出小爆款。比如:应用架构、应用场景。
  • 二是垂直技术型选题,选择某一个技术方向或产品某一功能模块进行技术分享,更偏向于深度上的探索,此类型主题的受众面取决于用户对该主题的关注程度。比如:技术原理解析、经验教程分享等。
  • 三是方案型选题,为用户提供某种创新使用或生态方案,比如 Discourse on PG -> MySQL -> TDB,或“TiDB+”等。

文章结构或提纲

然后,确定文章结构,指整篇文章叙述的结构或者提纲,通常包含开头、正文、结尾,有了提纲再去写作会更有方向性,更高效。这里可以参考后面的文章提纲参考

完善内容

指根据叙述结构后提纲,去完善文章的主体部分,每一部分相对独立的内容建议一口气写完。这一步可以 快速完成,多次迭代 。和写代码一样,每次集中精力,60~120分钟写一个部分,中间不被打断,这样的“时间块”的产出最高,也更容易挤出来。

开头和结尾这种重要的部分如果一开始没有灵感,可以先放放,让更精彩的文字来找你。

自我审校

  • 结构是否清晰、完整 :结构严谨、逻辑清晰、始终围绕主题、前有背景交代、后有总结,结构的完整、清晰大大加分
  • 内容可读性 :行文流畅,有过渡有衔接,无明显技术错误
  • 语言流畅与否 :用书面化的语言去表达,避免过于口语化
  • 错别字检查
  • 安全脱敏: 内容脱敏、公关上利好、不会引起争议

文章发布

接下来,你需要把内容发布在社区的网站上,这时候要注意 2 点:

  • 排版:
    • 比如多级标题的展示清晰,重点内容加粗,代码高亮等
    • 技术文章版块采用了 Markdown 编辑器,可以参考 Markdown 语法教程去优化
  • 版权声明: 为了保护你的劳动成果,建议你的原创文章加上版权声明,可以是禁止转载,也可以是转载需要告知原作者、注明出处等,然后加上版权符号 " © " 提示读者,这是一个版权声明。

版权声明 ©

【是否原创】是

【首发渠道】TiDB 社区,转载请注明出处

如果转载其他人的文章,也请注明出处:

【是否原创】否

【首发渠道链接】其他平台首发请附上对应链接

文章提纲参考

一般技术文章核心思路可以总结为以下四部分,当然针对不同主题,需要在以下结构上进行细分,不同部分有所侧重。

用户实践/案例

1、公司简介以及使用 TiDB 相关的业务场景介绍

  • 目前遇到的业务挑战,
  • 为什么要使用 TiDB
  • 在 TiDB 与其他数据库对比选型时候的思考

2、TiDB 应用场景 1

  • 业务场景描述
  • 技术架构描述
  • 业务收益

3、TiDB 应用场景 2……

4、总结的几个方向:

  • 从目前场景的试用结果看,TiDB 在哪些场景具有优势,归纳 TiDB 在该场景的最佳实践,为其他同行提供经验参考
  • 未来展位 & 希望 TiDB 进一步提升的方向

参考示例: TiDB 在马上消费金融核心账务系统归档及跑批业务下的实践

故障分析案例

  • 背景(包括 TiDB 的使用情况、技术架构等)
  • 遇到的问题 / 现象总结
  • 分析问题
  • 提供解决方案
  • 总结

参考示例: 如何分析和解决 TiDB 4.0 的写热点问题

方案类

1、背景

  • 新旧方案对比 / 当前存在什么样的问题(提出问题)
  • 原方案存在哪些痛点(总结需求)

2、新方案实践

  • 新方案简介
  • 主要架构
  • 如何使用
  • 核心价值

3、未来规划

  • 当前适用的场景
  • 未来适用的场景
  • 技术上的未来规划

4、总结

参考示例: 基于 Flink SQL CDC 的实时数据同步方案

不受欢迎的内容

如果你在社区写过技术文章,应该知道文章在发布之前都需要经过审核,会把一些不受欢迎的内容过滤掉,保证社区的健康发展,这些内容包括:

  • 违规内容: 内含黄赌毒、涉及政治等敏感话题的内容
  • 很水的文章 :做个人备忘、记录、笔记类的内容更应该是草稿而不是正式发表的文章
  • 杂乱无序的内容 :排版混乱,文章结构不清晰,内容逻辑不符都可以被定义为垃圾文章
  • 任何推广(招聘、广告、SEO等)方面的内容 :广告如:“个人视频教程、书籍推广等内容”,如果有这方面的推广需求,请联系 luzizhuo。

技术文章奖励规则

为了更好地嘉奖撰写技术文章的小伙伴能得到较为合理的经验值&积分奖励。每篇会根据 :是否首发;内容的难易;篇幅;对 TiDB 社区小伙伴有益度进行评审奖励,审核通过的技术文章

  • 最低 奖励 100经验值+100积分
  • 最高 奖励 200经验值+200积分

参考

InfoQ编辑如何写技术文章:敏捷写作

3赞

支持原创,支持分享

1赞

现在回帖由3->8了,这波调整有点鼓舞人心呀!

1赞

太赞了

:+1:

1赞