专栏首页技术那些事优秀技术文档的书写姿势

优秀技术文档的书写姿势

一、背景

写文档是程序猿进阶的一个必要步骤之一。

文档写的清楚,思路就更加清晰,也会让同事高看你一眼,多梳理业务也有很大帮助。

产品经理对需求文档基本是驾轻就熟信手拈来,但是大多数程序猿写技术文档却显得不够专业。

最近有小伙伴问怎么写技术文档,结合了多个优秀的技术文档的范例,总结了技术文档的框架。

二、框架

话不多说,直接上干货。

2.1 技术文档的架构

关键是能够条理清晰,然后配各种UML图,表格等。

2.2 考虑的因素

我们主要考虑:

  • 我们写作的目的是啥?
  • 看文档的对象是谁?
  • 主要想表达什么?
  • 应该表达哪些内容?
  • 怎样才能更有条理?
  • 怎样才更容易让读者理解?

三、推荐图书和软件

3.1 推荐图书

《大象UML》、《UML精粹》

3.2 推荐作图软件

工欲善其事必先利其器。

作UML图推荐Viso、ProcessOn、PlantUml、UmlStar、OmniGraffle等。

3.4 推荐思维导图工具

mindnode、xmind、ithougthtX等

四、思考

第二部分给出了技术文档的框架,引导我们去思考应该考虑的问题。

仅有这些还不够,实践是检验真理的标准,要去练习才能真正掌握这个框架。

另外看似有了框架啥都不是问题,照着填就完了,事实并非如此。

正如高考英语作文模板一样,框架都有了差不哪去,但是具体的内容千差万别,最终的分数还是有浮动的。

要想写好技术文档,写的更加专业还需要一些软能力,比如思维要缜密一些,画交互,画UML图的能力,画思维导图的能力的能力等,这些需要平时主动去学习和训练的。

如果你还是不清楚如何操刀书写,不妨多看看你吗公司技术大牛、架构师、CTO等,写的技术文档,先从模仿开始。

关于技术文档书写姿势,你有哪些妙招、心得,不妨留言分享。

本文分享自微信公众号 - 程序猿技术大咖(cxyjsdk)

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-06-22

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 微服务架构下的核心话题 (三):微服务架构的技术选型

    为了实现基于微服务开发的产品,或者说为了将单体应用重构为微服务架构时,将面临着众多技术框架的选择。大公司往往会有专门的部门或团队来负责自主研发自己的框架,以满足...

    xcbeyond
  • 难道程序员只把Redis当缓存?3大场景助你完美收割Redis实战开发

    微风拂面只在瞬间,如若没有对这一刻的思索,往往少许了些对于问题本质的思考、推敲,这一刻的感受,将不会激荡起心灵中对于本质的追寻。而后渐渐得将失去对于任何事物的看...

    xcbeyond
  • 应届生求职面试真的有那么难吗

    本周有幸参加了公司的校招(专场宣讲会),并作为一位技术面试官的角色出现在校园,让我回忆起了当年自己是如何参加校招、如何进行面试,当年的场景历历在目...

    xcbeyond
  • Wizard 开源文档管理系统 1.0 发布啦

    Wizard 是一款开源文档管理系统,项目地址为 https://github.com/mylxsw/wizard。这个项目是 我 在2017年就开始开发的,起...

    用户2131907
  • 总监突然把我拉进了一个群……

    大噶好,又是我,TAPD的产品经理圆圆。 上周一上班的时候, 我发现隔壁组来了个巨帅的小哥哥。 ? 有多帅呢?可以说,是吴彦祖+金城武的那种帅。 我立马就去企...

    TAPD敏捷研发
  • 在RPA项目中有哪些文档,如何使用这些文档

    RPA项目也同样遵循同样的方式,不同的厂商和公司定义的文档类型也不太相同,多的可能十几种,少的也要几种,具体的遵循方式和使用标准取决于公司内部的使用章程。

    RPA小葵
  • Swoole 船新版本文档发布了,是兄弟就砍我!

    Swoole的文档一直被人所吐槽,虽然内容很丰富,但看起来很费力,更新也稍有些不足,所以这次识沃科技专门组织了人力和资源重新打造这一船新版本的文档,让人眼前一亮...

    桶哥
  • SharePoint 2010 新体验3

    有时候,我们会有一组关联度很高的文档,它们都是属于某个主题,或通常互相引用。比如,关于某个项目的一组Word文档,或是TechEd会议的所有SharePoint...

    py3study
  • 用好DocNav - Part 2

    在DocNav中可以快速查看文档章节标题而无需下载该文档。如下图所示,点击红色箭头所指的标记,即可显示文档章节标题。若要查看某章节内容,可直接点击标题名称,从而...

    Lauren的FPGA
  • 为啥开发的文档能力是核心竞争力之一

    在开发团队里面一般产品的文档能力会比较强,很多开发的文档能力都非常弱,在我看来文档能力是一个程序员核心竞争力之一,文档能力强才能实现能力的快速发展。为什么语文在...

    用户5829239

扫码关注云+社区

领取腾讯云代金券