根据用法，软件可以分成很多类：

• 命令行软件
• 图形界面软件
• 软件类库/SDK

不同软件的文档的内容基本都是接近的，主要是各种指南，介绍如何操作软件，只是图形界面的软件截图会多一点。然后，软件类库或者SDK，会提供API文档。

下面我们会介绍下如何编写软件的技术文档。

工具选择

传统的文档形式有CHM、PDF、Word文档等等，使用FrameMaker、Microsoft Office等软件制作。

现在一般都是在线网页，有一系列的站点生成器，比如Sphinx、mkDocs、Docusaurus、Jekyll、GitBook等等，使用markdown、restructuredText等标记语言编写。这些工具通常还支持生成DITA、LaTex等文件。

针对API文档，也有专门的工具，可以直接根据程序源码生成文档，比如Sphinx、JSDoc、JavaDoc、Swagger等。

更多工具介绍可以见这篇文章：技术传播领域的工具。

内容安排

文档站点主要由目录树和内容页面构成。内容可以根据软件特点进行分类，比如软件介绍、使用指南、API文档、常见问题、变更记录等等。

API文档的内容安排上，除了单独的接口页面，还要有能显示所有接口列表的页面，方便浏览。

格式规范

技术文档通常需要遵循一定的规范。这里以JavaScript语言的API文档举例。

首先，API可以进行一个分类，比如按命名空间、类、接口、定义、事件、枚举进行划分。

然后不同类别的内容，也会有编写的规范。

命名空间主要列出它包含哪些静态方法、对象、类。

类主要包含它的属性、方法和继承关系。TypeScript中的接口（interface）和类相近。

事件主要描述它包含哪些参数，要怎么绑定事件。

示例文档

命名空间

## Namespace XLH.OCR

### Methods

* getOCREngines()
* on()

### Properties

* error
* version

### Members

* Enum_OutputFormat
* Enum_SegmentationMode

### Classes

* BaseOCR
* OCRSpaceOCR
* GoogleOCR

类

## Class GoogleOCR

Extends `BaseOCR`

## Constructor

Creates a new Google OCR object.

Syntax:

\```ts
new GoogleOCR()
\```


## Methods

### detect()

Detect text in a image.

Syntax:

\```ts
detect(source:HTMLCanvasElement|HTMLImageElement):OCRResult
\```

Parameters:

source: the image to detect. It can be a canvas element or an image element.

## Properties

### apiKey

The API key for Google Cloud OCR API.

接口

## OCRResult

Syntax:

\```ts
interface OCRResult{
  textLines:TextLineResult[];
}
\```

事件

## OCRProgressEvent

Triggered when the OCR progress info is updated.

Syntax:

\```ts
XLH.OCR.on("OCRProgress",function(event:OCRProgressEvent) {
  console.log("progress: "+event.progress);
})
\```

Instance properties:

progress: progress of the OCR action. The value is between 0 and 1.

多普达818pro

我爸2007年炒股赚钱后，买了台多普达PPC，让我第一次接触到了智能手机。

接触了各种论坛，学会安装软件、刷机、制作ROM，折腾各种GPS软件。

经由Pocket DOS，我又开始折腾给电脑安装各种系统，封装启动光盘镜像、接触了AU3编程。

三星J708

我爸给我妈买的三星翻盖功能机。1700元，有拍照、FM、百宝箱等功能。

支持各种安装Java软件，不过屏幕分辨率只有128x160，而且性能有限，可以适配的软件不多。

我还跟着教程学习了J2ME开发，写了一个乘法软件。

HTC G1

安卓出来后，2010年上高中前，我让我爸给我买了台二手HTC G1，1100元。

当时安卓的热度很高，安卓网、机锋网的版块可能都有上万的新帖。我学习了安卓软件安装、刷机，了解了recovery、app2ext、root等等概念。

G1是全键盘手机，当时装了GBA模拟器玩光明之魂玩得挺爽。

12年家里买了汽车，我还在G1上安装了凯立德来做导航。

中兴U956

13年高考结束，我考虑买台自己的手机。当时江南大学给我发了移动的卡，我就打算买台支持移动网络的手机。

一开始我是想买HTC的，但看了下几款手机都比较贵。然后无意中刷到了中兴U956，搭载联发科MT6589四核CPU、1GB内存、5英寸OGS全贴合屏幕，还只要1000元，于是喜欢性价比的我直接就买了。

买了U956后不久，小米推出了红米，类似的配置，只要799。

当时5寸的屏幕已经是非常大了，拿出去别人都觉得有点夸张。

那个时候第三方ROM还是很多的，我自学ROM移植，移植了乐蛙OS、MIUI等系统。最后停留在乐蛙OS 5。

iPhone 5c

偶然逛论坛，了解了iPhone有锁机。这种iPhone价格很低，没用过iPhone的我也心动了，找了家TOMPDA的卖家，花1500元买了台16GB蓝色的iPhone 5c。

一开始用卡贴适配移动卡，但这种破解方式不完美，后来超雪出了适合电信的较完美的卡贴，我又买了张电信卡来用。

升级系统到iOS 8后，我直接越狱装Cydia，安装第三方输入法、各种插件、本地Python用来跑搜狗校园网代理等等。

为了体验iOS开发，我还在电脑上装了MacOS X Mountain Lion黑苹果系统。

iPhone 5c是我大学时候的主力机，从大二用到研一。

HTC 8X

Windows Phone作为当时三大手机操作系统之一，我也一直想体验一下。于是300多买了台二手的Verizon HTC 8X。

2015年，我跟着视频较系统地学习了Windows Phone开发，还上架了江南听雨BBS的客户端。

摩托罗拉G2

因为要去美国，有锁的iPhone不能用当地网络，我就又花700多元买了台国行的Moto G2 (XT1079)，移动联通双卡4G，8GB存储，1GB内存。

我给它刷了基于安卓6的CM系统，还有绿色守护，在当时使用起来还是比较流畅的。

这台机器的一个特点是使用了JDI的5寸 LCD屏幕，看起来有斜纹，但显示效果还是不错的。

Yota Phone 2

俄罗斯的手机品牌，推出了双屏手机，前面是OLED屏，后面是墨水屏，而且刷新率很高。

我花600多元买了台二手的来体验。看书效果还是很好的，我用它看完了哈利波特的前两部。

Yota的FM功能支持的频率范围比较广，还能收听FM85校园广播。

可惜，研一的寒假，被汽车碾碎了。

海信A2 Pro

Yota Phone坏了后，我还是想买台双屏手机。于是2018年花2500元买了台海信的A2 Pro，是我买的最贵的手机。

它也是前面OLED，后面墨水屏的设计。不过OLED屏的频闪比较明显，需要我把亮度开到最高，然后用护目镜调节屏幕颜色来调暗屏幕。当时安卓7上护目镜效果还比较不错。

夏普Aquos S2

2020疫情期间，A2 Pro的关机键失灵，我便又考虑换机了。

当时主要想买台轻便的LCD手机，于是看中了屏幕质量很好的夏普Aquos S2，正好有家店，700多能买到全新版本。这台5.5寸的全面屏手机，重量只有140克，搭载了骁龙630的CPU，比625性能还好一点。

不过这款2017年推出的手机，在2020年用，性能上还是略显捉襟见肘。

买S2前，我还尝试了小米CC9，但它的OLED屏看一会就眼睛疼，最后还是重新选择用LCD手机。我给我妈挑的两款手机，小米5x和华为nova 7 SE也都是LCD屏幕。

OPPO A72

2022年，夏普S2频繁重启，我就又打算换台轻便的LCD的手机。

因为已经流行OLED手机了，可选择的机器不多，我最后选择了重量175克的OPPO A72。它有1080P的全面屏，天玑720处理器，4040毫安时的电池，虽然是千元机，还是非常够用的。

其它二手手机

我还买了些便宜的二手手机，用来体验和收藏的：

PPC：HTC D810、P860、Diamond、CHT9000、818，当年几千元的PPC手机，只要几十元，我把有名的几个型号都买了。最近又49元买了台2013年出的Opticon H-21带激光扫码的PDA。

Windows Mobile 10：Windows 10出来后，我买了台诺基亚的Lumia 822来体验，学了点UWP编程。这台手机搭载了OLED屏幕，和Windows手机的黑色背景搭配还是很合适的。

安卓：小米1S青春版，它搭载了半反半透屏幕，我本来以为它有护眼效果，实际体验发现反射率很低，而且屏幕反光还比较严重。

今天是我的生日，我妈生下我的日子。这个日子对其它人可能很普通，但对于我们一家人却是不一样的日子。不过，我也没做什么特别的事情，就像一个平凡的工作日那样度过，可能不同的就是我在写这篇文章。

30岁的我，日常是个什么状态呢？早上睡到8点15，出门骑6分钟的自行车到公司所在的写字楼，在食堂吃好早餐，然后上楼打卡上班。日常就是写文档、写博客、写sample级别的程序、分析市场、了解竞争对手、开会，闲了就忙点自己的事情。午饭晚饭也都在食堂解决。下班后先逛圈公园，然后回家刷刷手机。洗澡后洗下衣服，做10个引体向上，差不多11点就躺床上了。周末主要宅家，维护自己的软件，偶尔做饭，但大多数时候还是去外面吃。

刷手机主要还是看视频，看的内容很大程度受到它的推荐机制影响。不过还是看了挺多种类的东西：

• 香港电视剧：从小时候看过的金庸武侠、《寻秦记》、《西游记》，到没看过的《上海滩》、《妙手仁心1》、《先生贵性》、《郎心如铁》、《九五至尊》
• 内地电视剧：央视版《笑傲江湖》、《爱我就别想太多》、《狂飙》、《与凤行》、《莲花楼》、《庆余年2》、《奋斗》、《人生之路》、《我的阿勒泰》
• 外国电视剧：《宫》
• 综艺：《Running Man》、《X-Man》
• 游戏：Dota、《红色警戒》、《三国志曹操传》、《未定事件簿》
• 其它：云养宠物、心理、健康相关的视频

30岁了，家里也会介绍对象，但我比较看重一个人日常的文字表达，不喜欢聊天，加上好友后，看到朋友圈啥都没有，我也就懒得进一步联系。或者是朋友圈有很多内容，但我一看就觉得不合适。再就是日常接触到人。但日常接触人有很大的风险，容易自我感动，我这里再就情感和工作问题总结下。

其实情感和工作问题是相似的，你是什么样的人，找什么样的工作。但很多时候，我们对自己和他人认识不清，导致我们遇到不少坎坷。但人生也会因此变得丰富。

1. 关于预想。我们不可能自己去经历所有事情，所以需要预想，来少走弯路。但世界还是复杂的，我们预想的东西往往和实际不符，有时还是要直接做，少假想。
2. 不要怕难。在旅行的飞机上，一位91年已经做妈妈的女同事问我考不考虑结婚，我说我觉得我自己都照顾不好，然后生下孩子，孩子也要在人世间受苦。这个问题自古就有，晚婚的老舍在《婆婆话》里也提到，人生来为牛马。但这位同事很乐观，她说你都没做怎么知道难呢，你想的不一定你孩子也这么想。这么一说，我也乐观了很多。但刚刚聊完，我摸到包里的削皮器，把手划伤了。看到鲜血涌出，我不由得心慌，好在空姐和同事帮忙止住了血。我瞬间对自己更没有信心了。不过之后我回想，船到桥头自然直，有困难咱就解决困难不就行了。但如果这个困难真的很大，还是要学会避开。
3. 学会休息。中国翻译《莎士比亚全集》第一人是梁实秋，为什么呢，因为别的翻译家在翻译完前就挂了，只有他活了80几岁，有能力翻译完。所以我们工作生活，既要注重当下，也要有长远的考虑，身体是革命的本钱，要学会劳逸结合。
4. 学会找乐子。其实工作、学习，换个角度看，都是玩，而且是对社会能有点贡献的玩。只是玩得久了，没有玩的心态了。我们重新拾起这种玩的心态，工作学习也会欢快很多。

30岁，我会发现很多从前的想法并不是正确的，就像《大宋提刑官》里的宋慈，每破一个案子，就进一步认清这个世界。我还是希望能像《神探狄仁杰》那样，有自己崇高的目标，不断壮大自己，战胜敌人。

如果小时候看过《神探狄仁杰》，可能会记得狄仁杰这样的一段自我介绍：在下姓狄，名仁杰，并州人士，官同凤阁鸾台平章事，加黜陟使，兼幽州大都督。

并州就是目前山西省的省会太原的古称，因为其位于吕梁山和太行山之间的盆地得名。而山西整体的地势就是“两山夹一川”。山西历史悠久，春秋时的晋国，南北朝时的北魏主要就位于山西。国家大一统时，也是经济、文化发达的地区，在明清时晋商十分活跃，在革命时期也是主要的革命根据地。

我们此去山西，主要便是感受山西的人文文化，走马观花了晋祠、五台山、恒山悬空寺、大同华严寺、云冈石窟、雁门关、平遥古城和乔家大院等景区（见下方地图）。下面我将按时间顺序记叙这次旅行。

第一天

乘MU5242次航班从杭州前往太原武宿机场，可能因为梅雨，晚点1个小时，晚上9点多才到达。入住酒店后就直接休息了。

第二天

早上7点30出发，前往太原西边的晋祠。晋祠有一汪泉水、很多的古建筑、几千年的参天大树，不过我对建筑、雕塑什么的实在是个外行，就像逛公园一样逛了一圈。

接着出发前往东北方向的五台山。五台山不是一座山，是由一系列大山和群峰组成，上面有大大小小很多的寺院。《华严经》提到五台山是文殊菩萨的道场，而后它的名气也越来越大。

我们到五台山后，先前往普化寺游览，然后登菩萨顶，逛了一系列寺庙，下来后又去了五爷庙。

我最喜欢的还是普化寺，还在那里上了香，可能是那里比较清静。

晚上，我们在五台山北面繁峙县砂河镇住宿。这个小镇楼房都不高，也比较清静。

第三天

上午8点出发，前往北岳恒山，参观恒山十八景之首的悬空寺。我们先到了一个游客中心，然后乘摆渡车前往景区。

进去后，我们在观光区远观悬空寺。悬空寺依托崖壁而建，看上去像悬空在悬崖之间。

悬空寺景区有广播一直在放同一首音乐，还挺好听的。我回去后查了下，是山西当地团队创作的歌曲《千山千缘》，表达了苦寻梦中奇缘而不得的惆怅。

离开悬空寺，我们前往大同市区，到了大同古城里的华严寺。这座寺庙的建筑主要是辽金时期的，里面有各种壁画和塑像。

之后，我们前往西北方向的云冈石窟。云冈石窟主要有20个石窟，全部由北魏建造。最西边的20窟，是最具代表的石窟，外面没有石壁，是露天的。而东边的许多窟则比较径深。

晚上在大同的龙聚祥吃了烧麦，没有嘉兴的肉烧麦好吃。

前往大同的路上的景观和在内蒙古赤峰看到的会比较像，是一座座山，山上是草原，零星有几棵树。

第四天

第四天山西下雨了，高速封路，我们只有走各种小路向南前往雁门关。沿途穿过朔州的村庄，还远远地看到了应县木塔。一直到中午才抵达雁门关。

明清前，我国统一多民族的疆域还没有形成，雁门关北面还属于少数名族的范围。这里东西山岩峭拔，中有路，所以便在这里建立关隘，来抵御外族入侵。叫雁门是因为大雁也过不了两边的山，只有从较低的雁门关的位置飞过。

来到实地后，的确有种荒凉的边境的感觉。不过现在的雁门关都是新建的，当做景区来运营，就少了点意思。

离开雁门关，我们就往南前往平遥古城。因为距离远，一直到傍晚才到。

平遥古城是一座保存完好的古代县城，有城墙、店铺、街道、寺庙、民居等各种组成成分。历史书中提到的日升昌票号也位于此。

主要的街道商业化严重，偏僻的小路又乌漆墨黑一片，我也没有多逛。看到有卖叫做推光漆器的店，是用漆涂在各种器物的表面上所制成的东西，主要都是首饰盒，算是当地特有的。

第五天

行程最后一天，我们前往祁县的乔家大院。本科的时候看过《乔家大院》电视剧，印象最深的有两个场景，一个是张译从城墙上下来，一个是摄像头放在院子门口，乔致庸缓缓走入宅子。

乔家大院有很多院组成，中间有一条甬道连接。我实地到访后，后一个场景应该是在中堂，进入院门，正面正房，两边偏房，中间一口水缸，有挂着大红灯笼。

这些房子有书房、客房、餐房、厨房等等功能分类，屋子里有各种家具，让我们了解了当时人们的生活场景。

八国联军侵华时，慈禧西逃经过乔家大院，乔致庸借了30万两白银给慈禧。后来慈禧送了九龙灯，至今能在乔家大院看到。晋商依附官府才得以繁荣，在清廷衰败后，晋商便也衰败了。

离开乔家大院，我们便回太原，等待返杭的飞机了。

其它

我再稍微讲下旅行中的人。

先说下和当地人的互动。时间短暂，交流最多的还是我们的导游阳阳和司机师傅。阳阳是94年的女生，山西文水人，也做了10年导游了，有北方女生的爽气。她去年结婚，和在北京工作的老公处于异地状态。司机师傅常年在外，老婆也是导游，三个月没见了，正好在云冈石窟停车的时候两个人碰见，打声招呼后就又继续行程了。原来大家都在努力生活。

都说旅行能反映人的品性，就说我自己吧，不太会整理东西，买了个削皮器放包里，结果翻包的时候划伤，然后血液涌出时还不太会止血，好在有空姐和我们大名同学照顾，创可贴、碘伏棉签样样都有。

感谢公司组织旅行，让我看到了我们大名同学不一样的一面，也向大名同学学习了很多。

而我的话，则比较多的离开座位，去外面散步休息。

当代的工作，通常已经不再是血汗工厂的工作。我们其实不需要8小时一直埋头做事情。休息是正当的行为，而且能帮助提升工作效率，并延长工作寿命。我们需要有空闲的时间，来总结我们的工作，对未来有一定的规划。

最近有句话叫世界是个草台班子，规则本来就是人定的，存在缺陷的，我们不必完全照着规则来，需要灵活变通。

例：https://blog.xulihang.me/the-essence-of-computer-programming/#:~:text=%E6%9D%A1%E7%A0%81

我们打开这样的一个链接后，浏览器会给出对应的效果，但我们直接刷新页面，则不会有这种效果。

在程序世界里，充满了这样的条件判断。我们日常写程序，其实不会涉及很复杂的算法，更多的是处理这样的细节。编程的确是个细致活。

我们公司的年会一般上午进行工作总结，下午进行表彰、表演节目和进行团建游戏。

因为我们公司人数不多，可以在一个小报告厅完成所有活动。公司基本上每个人都彼此认识，工作几年后，对各自想说什么、平时表现如何其实都已经比较清楚了。年会上有很多个人发言的机会，或许是因为太熟悉，如果表达过多的确会让人感到厌倦，如何适度地表达不是件容易的事情。

表演节目，以前是强制分部门出节目，结果很多人不想表演也被凑一起组成小组。今年改成了自愿报名，的确轻松愉快了很多。毕竟表演节目，要发自内心去做才开心，才能表演得好。

团建游戏，我个人其实不喜欢小组对抗太强的项目，平静点的需要协作完成的活动我还是比较喜欢的。这次有一个捡橘子游戏挺有意思，是每组派五人出场，前面四个人要蒙着眼睛，最后一个人当指挥，每个人手扶着前一个人，通过拍打传递信号，由第一个人捡起地上的橘子。

每年各种团建项目，难免会有重复的项目。我发现玩过的项目再玩的确没那么有意思，人对于新花样的追求还是挺高的。

热闹的年会结束后，还是要回归日常的工作和生活。

编程和开车一样，学习它提供的接口，来实现各种功能。只是汽车提供的接口比较有限，而计算机世界的接口纷繁复杂，让人常常陷于这些接口之中，忽视了编程的本质。

汽车的工作原理、计算机的工作原理，我们在使用它们时，往往不需要知道，但要用好它们，则需要有一定的了解。同时，我们也要对我们需要解决的问题有足够的了解。

我今天碰到一个React Native用户问为什么某个条码扫描库会有误识别的问题，是不是原生代码哪里没配好。这是他对条码识别这个图像处理操作的复杂性没有认识，觉得修改下原生代码，就能神奇地解决问题。

1. 我告诉你我的名字，你也告诉我你的名字。（神雕侠侣）

   剪辑链接

2. 想象对方会说什么。（先生贵性）

   剪辑链接

3. 发现自己得病以喜欢另一个人为理由提分手。（先生贵性）

   剪辑链接

待更新。

虽然我是男生，但出于好奇，我也下载了米哈游开发的律政题材的《未定事件簿》体验。我发现其实没有做很强的代入感，可以跳脱出来，以视觉小说的形式看女主和几个男主发生的故事，还挺有意思的。

下面讲下它是怎么玩的。

首先是一条主线，讲刚工作的律师和四位男主接受律师委托、处理各种发生的事件。四位男主分别是青梅竹马的侦探、同样是律师的上司、心理医生和公司总裁。

过剧情有三种形式，通过交互对话开展的剧情、利用卡进行辩论的战斗和综合上述两者的庭审。卡需要消耗叫做女神之泪的资源进行抽取。卡有等级、技能、卡面、星级等可以升级的属性，并且还会附带剧情或者私语，以及短信与通话。为了通过战斗，避免卡关，需要玩家完成各种日常活动，不断抽卡和提升战斗力。

除了主线，还有个人线。是女主和某个男主的专属剧情，能看到他们的感情进展。个人线需要通过提升和主角的好感度来解锁。

此外还有各种活动、小游戏等。

这种游戏的氪金属性比较强，完全不花钱容易卡关。不过我们可以以时间换金钱，通过每天完成日常来慢慢提升战力和等级。游戏也是通过这种方式提升活跃度。把每天的体力用光，似乎就是赚钱了。

然后讲下它有意思的一些地方吧。

游戏中模拟了各种男女间可能发生的剧情，有的剧情一般，但有的剧情比较合理，所以总归是有吸引人的地方。

比如上司左然，29岁了但没啥恋爱经验，要看《恋爱心理学导论及实操方法》这样的书，结果闹了不少笑话。地铁里碰到女主却没想好该说什么就招呼也没打。和女主出席酒会，结果女主帮同事要明星签名时和对方笑着说了几句就吃醋了。但在工作和生活中，左然还是能够依靠的人。女主对他一直很敬重。

再说莫弈，他的设定是某个国家的王子、心理医生、大学教授。他会沉稳很多，和女主调查了关于pua的系列案件。和他的互动中，我们能了解各种心理学知识，也能对爱情是什么有思考。但有点白切黑，不时让人感到害怕。这是游戏在展示男主也存在缺点。

公司总裁陆景和，平时吊儿郎当的，叫女主姐姐。和他的相处会比较轻松有趣，但也会看到他有压力的另一面。

青梅竹马的夏彦，同龄人，和他相处时，能看到女主在关系中主导的一面。

最后是一些吐槽的地方。

1. 剧情一开头男主就都已经喜欢女主了，没有一点需要攻略和拉扯的感觉。
2. 好感度可以通过每天和男主角互动交流进行提升，每天额度有限。这个倒是，感情是需要时间的，不过每次交流好感度都能提升？现实中过多交流好感可能反而会下降，游戏对情感的模拟较差。
3. 穿插在剧情中的战斗没啥意义，完全就是为了让用户卡关然后去氪金存在。虽然的确增加了上瘾性。
4. 很多剧情比较想当然，没啥深度。
5. 含糊。男主邀请女生去射击等活动，却对理由支支吾吾，不是很真诚。

总体上《未定事件簿》还是做得不错的一款游戏，配乐、画面都是很好的。在当下这样一个比较糟糕的现实环境里，这样一款恋爱游戏能让人勇敢面对现实、相信爱的能力。