如何写好一篇技术性文章 | 青训营笔记

乌云暮年
279 阅读5分钟

这是我参与「第五届青训营 」伴学笔记创作活动的第 4 天

前言

本篇文章的受众：

  • 想要系统学习写作、解决写不好文档的懂点（如主题不清晰、内容杂乱、语言啰嗦）的小伙伴。
  • 想要进一步提升写作技能的小伙伴。

本篇文章的目标：

  • 系统地认识写作： 了解写作的底层逻辑和常规步骤、掌握通过的基础写作技巧。
  • 写出清晰的文档： 帮助你写出符合读者预期的、有逻辑、有框架、可读性强的文档。

一、了解读者

01为何了解读者

  • 保证写出可读性强的文档

02何为了解读者

  • 明确读者身份：小白用户 or 资深用户 ？ 运维人员 or 开发人员 ？

  • 明确读者阅读目的：了解一个概念、完成一个步骤，还是查阅一个参数解释？

  • 明确读者所需信息：根据读者的认知能力提供所需信息，打破信息茧房。

    • 信息差（狭义）作者和读者之间的认知差异，常见的信息差来源：专业术语（术语出现的位置使用提示进行解释）、相似物（例如出现相似的功能，需要加入文档帮助读者辨析）和新事物（所有新出现的事物都要充分解释其来源）

03如何了解读者

  • 主动走进读者：

    • 邀请同事评审：把身边同学作为目标受众，获得反馈意见。
    • 读者访谈：可以与读者进行访谈或聊天，了解他们对文档的期待、建议和意见。
    • 文档支持群：建立文档支持群，收集第一手的文档问题。这个是指可以建立相关读者或者粉丝群，用来第一时间分享文档同时可以收集高质量反馈，也能明白读者的需求。

  • 头脑风暴（日常反思）：

    • 读者从哪里来：读者阅读这篇文档的目的是？要完成什么任务？读者最开始是什么状态？身边有哪些资源？
    • 读者在哪儿：读者此时所处状态？比如，读者怎么确定他们处于文档里说这个状态？
    • 读者到哪里去：为什么要告诉读者这些内容？对他们有什么用？下一步要做什么？

二、结构化写作

01.何为结构化写作（意义）

  • 理清信息之间的逻辑关系
  • 把无序信息排列为有序信息
  • 创建逻辑且顺产的信息流
  • 有逻辑有条理地提炼和组织内容

02.为何结构化写作（好处）

  • 为作者理清写作思路： 帮助作者在清晰分类的基础上全面考虑问题，找到写作的方向和重点。
  • 为读者降低阅读成本： 帮助读者快速锁定目标信息，获取重点信息和核心观点。

03.如何进行结构化写作

结构化写作三步走：

  • 搭建文档框架：核心原则：结论先行、以上统下、归类分组、逻辑递进

    • 结论先行：开门见山把核心观点或中心思想放在文章开头的位置，让读者一目了然。
    • 以上统下：上层结论是概括总结，需要下层信息进行具体解释和说明。
    • 归类分组：把相关联的信息按照一定的标准进行划分归类，归为同一个逻辑范畴。
    • 逻辑递进：按逻辑顺序递进排列素材。

  • 填充必要信息

  • 巧用结构化呈现：呈现方式：有序列表、无序列表、表格等

结构化对比： 结构化对比.png

三、写好标题

01.何为标题

标题：指明文档内容的概括性语句

  • 总标题：文章核心内容的体现
  • 副标题：对总标题加以补充和解说
  • 分标题：文档内的分级标题，能清晰地显示文章地层次

02.为何要写好标题

  • 可提升浏览量，更容易被引用。
  • 帮助读者快速了解文档的主要内容。

03.如何写好标题

可以遵循 SPA 原则 Simple（简明扼要）、Proisft（利益相关）、Accurate（准确客观）

  • 简明扼要：即我们的标题不宜过长，建议控制在 10 个中文字以内，只保留核心关键字即可。
  • 利益相关：标题所要体现目标读者所关注的内容及读者切实感兴趣的点。
  • 准确客观：不宜过多的表达我们的主观情绪，在字数有限的情况下，概括出全文的核心本质。而概括全文是运用了结构化思维中的以上统下

标题示例

标题示例.png

四、极简写作

01.何为极简写作

极简写作不是越短越极简，也不是字越少越好。而是为了简化读者理解信息的成本，用最精炼的语言概括最有价值的信息。

02.为何极简写作

  • 节省时间
  • 易于理解
  • 减少成本

03.如何极简写作

  1. 保持一致： 最简单、最易忽略，例如称呼、信息归类，描述顺序和出现顺序、所属关系等。 保持一致——参考.png

  2. 避免啰嗦： 简化效果最直观，需在长期写作训练中习得，比如避免口语化、叙事反复等。 避免啰嗦——参考.png

  3. 提供路标和索引： 方式多样，例如标题要起到索引的作用、缺少方位的指示、同时预期结果等。 提供路标和索引——参考.png

五、检查文档

01.何为检查文档

  • 对文档的“体检”

    • 写作：以创作者视角表达和呈现信息。
    • 检查：以批判者视角审视已经写好的内容。

02.如何检查文档

先冷却，后自查

  • 主题

    • 主题是否明确且聚焦，且符合目标读者的需求？
    • 内容是否过于发散，是否跑题？

  • 标题

    • 是否符合 SPA 原则（简明扼要、利益相关、准确客观）？

  • 结构

    • 内容是否遵照一定逻辑顺序？
    • 是否符合结构化写作原则：结论先行、以上统下，归类分组、逻辑递进？

  • 内容

    • 文字表述是否简单清晰，不“拖泥带水”？

引用

  • 字节内部课《通用素质 - 技术写作原理》

希望学到知识的小伙伴可以给我点个赞~❤️❤️❤️

avatar
文章
阅读
粉丝