你会“写好”一篇技术类文章吗

前言

        如标题，写和写好一篇文章完全不同，写好既要调理清晰、结构合理，又要有血有肉、读者看了简单易懂。

1、准备构思

        无论任何类型技术文档，在落地前都需要构思准备；如系统介绍类，要思考如何用简单易懂的呈现方式，能够介绍清楚系统的前世今生、核心功能、核心技术、潜在问题、系统发展及规划等；如最佳实践，如何用通过背景介绍，清楚的描述问题痛点，并通过何种技术方案去解决及实现；如题重构类，前期要有大量的业务和技术梳理，才能最终落地文档。

2、整理大纲

        目的：写大纲的唯一目的，就是明确范围，确定每个章节或题目的重点。

        我的习惯是，写任何文档，都通过思维脑图整理大纲（在线、离线都可以），这样会有整体思路，逐步细化大纲及内容，最终形成文档。就像写代码一样，先概要设计，明确功能范围，再详细设计，最终代码落地。就如本文档，也会现有大纲（不过这个大纲略简单）：

3、丰富大纲及排版

        基于初版大纲，明确范围后，细化每个章节标题；

        明确每个章节的重点内容，知道每一页问题要体现的重点，而不是凑章节字数；

        明确每个章节呈现方式，无论是PPT或文档，要知道用何种方式体现，读者/听者更易懂，更直观；

        确保整体文档结构流畅，目录结构清晰，没有前后矛盾的情况。

4、文档落地（重构类文档结构）

        基于细化的大纲，落地文档，就像写代码基于一个规范细致的详细设计，会游鱼得水，不会或者很少出现返工的现象；基于之前经验，列举重构类技术文档主要结构：

4.1、背景痛点

        基于前期梳理，描述重构的背景，也就是为什么要重构，提炼关键痛点，包括业务痛点、功能痛点、技术瓶颈，痛点越痛，优化的价值才越大。

4.2、重构收益

        描述重构后对业务、功能、技术上有什么收益，可以用具体量化数字；收益是评审技术方案的重要参考。

4.3、迭代范围

        重构主导人，需要制定迭代计划，根据优先级；因为技术类重构一定与业务项目冲突，要考虑资源、时间、新老版本等一系列问题。

4.4、方案架构

业务架构

        主要从产品功能上体现，按业务域划分，面向产品和业务人员。

技术架构

        如果是全面重构，整体架构可能都会改变，如果是局部，可以在架构图中放大本地改动的重点，弱化未改动部分；架构图一般可采用分层架构体现，以下是一个简单的架构框架。

核心技术方案

        这一部分很重要，需要体现本次重构优化的核心技术，如缓存架构方案、底层数据结构优化方案、接口性能优化方案，每一部分都需要体现实现的重点，如何解决前面的痛点。

灰度切量方案

        如果是平滑切量，需要提前灰度切量方案，甚至回滚方案，如何确保平衡，不影响线上用户，并保证切量的一致性（一个用户全链路数据的一致性）；

流量录制回放方案

        重大的重构都会结合流量录制回放，是研发侧确保新系统稳定性的重要手段；也就是把线上流量在新系统执行一遍，使用真实流量执行重构后的逻辑，验证正确性；这部分可以使用开源的，也可以自研。

4.5、排期

        有了详细设计后，首次迭代的排期是要给出的，后面迭代可以有大体节奏，具体可结合实际业务需求优先级，与业务、技术负责人同步，并达成一致。

4.6、注意事项

        这一项比较简单，列举迁移关键节点及注意事项，最好有个待办清单，每次站会可以过清单。

以上，就是结合之前经验，整理的一份关于重构类的技术文档编写参考，希望大家一起探讨学习！