4.技术文档的结构
约 2552 个字 预计阅读时间 9 分钟
为什么要写技术文档¶
- 告诉别人你做了什么
- 报告老师：我学习了，会做了，求毕业
- 实习报告
- 开题报告
- 毕业设计报告
- 毕业论文
- 向同行炫耀：我已经做出来了你就憋瞎忙了…（比如当年的Bernoulli兄弟）
- 科研论文
- Poster
- 报告老师：我学习了，会做了，求毕业
技术文档要点¶
- 为什么要做，有什么问题要解决
- 别人怎么努力解决的，哪里不够好
- 你做成了什么
- 你是怎么做的
- 验证一下
- 总结与展望
结构¶
全局与局部¶
- 核心内容与各个分支的关系
- 核心内容是统帅，要突出，各个分支要围绕和服务于核心内容
- 局部要服从全局，跟主旨无关的材料和观点，要加以裁撤，毫不吝惜
- 初学者往往堆砌材料，不善于取舍，以至于形成局部膨胀而游离于核心之外的情况
开头与结尾、段落与层次¶
- 豹头、凤尾
- 开头要一鸣惊人、引人入胜
- 结尾要言尽意不尽，令人回味无穷
- 开头
- 申明写作的目的（要解决什么问题
- 说明写作的意义（对解决问题有什么帮助或者效果
- 挑明写作的必要性
- 宣示论文所要探讨的内容
- 开宗明义亮出论文的核心论点
- 结尾
- 对全文的归纳、总结
- 从论题联系现实，展望未来或提出希望
- 言尽即止
过渡与照应¶
- 过渡时处理段落与段落之间、层次与层次之间互相衔接的一种手段
- 尤其在转折和跳跃之处更需要过渡
- 照应指的是前后文互相关照与呼应，从而使整篇文章血脉贯通，浑然一体
标题与摘要¶
-
标题
- 文章的标题是精炼的短语
- 语句尽可能精确、简练
- 说明文章的要点
- 帮助展示文章的主题
- 先给出文章的写作目的，然后起一个比较粗糙的标题，在完成全部写作后重新校正标题
- 标题的关键在于长度、选词和结构
- 选词准确，短语准确，8-12个单词合适
- 考虑作为页眉时的观感
-
摘要
- 给出~论文~工作的主要内容，包含一定的细节内容
- 三段式
- 问题/背景与前人工作（被你解决了的缺陷与不足，被你解决了的社会问题，前人工作的缺陷）
- 本人工作（基本研究方法）
- 一定不能用“本文阐述”，因为是写自己的工作而不是这篇论文
- 本文给出了什么解决方案
- 通过……（步骤），采用.…..（技术），做到了……
- 实验结果和重要结论
- 改进/提高了多少（自己的工作做得怎么样）
- 经过测试验证，达到了……效果
- 绝对不要讲还要怎么改进
-
一般不超过200-250字，或半页篇幅
课内讨论6：撰写摘要
实习报告¶
- 项目概况
- 背景介绍
- 工作任务及内容
- 工作成果及水平
- 完成了哪些任务
- 工作中的难点有哪些，如何解决的（技术含量）
- 项目收获
- 技术方面的收获
- 其他方面的收获
- 工作建议
开题报告¶
- 标题要精准概括内容
- 项目背景
- 社会发展的需要、课题的意义
- 同类产品（研究）现状
- 项目来源及概况
常见问题
- 缺少同类工作的调研
- 目标和任务
- 目标：最终要做成什么样子，各项指标
- 任务：为了达到目标，要先后做哪些事情
常见问题：
- 任务目标分不清楚
- 直接给个功能清单
- 可行性分析
- 技术可行性
- 环境条件可行性
常见问题：
- 过于简短，不成章节
- 分析一堆，没有结论。
- 初步方案及关键技术
- 初步方案：怎么做？先做什么后做什么
- 关键技术：一般不超过3项
常见问题：
- 方案与任务，傻傻分不清楚
- 只有文字没有流程图
- 只有图没有文字
- 太多“关键”技术，且没有技术含量
-
预期工作结果
- 最终完成什么东西
- 满足什么要求
常见问题：
- 罗列功能清单
- “结果”甚至不是个名词
- 只有一个名词
- 进度计划
课内讨论7：评价开题报告
毕业设计报告¶
每一个部分的开头都需要有“帽子”，末尾要有“本章小结”。
0. 摘要¶
- 一般300~500字
- 社会背景、工作意义
- 存在问题
- 本文给出了什么解决方案
- 通过……（步骤），采用.…..（技术），做到了……
- 经过测试验证，达到了……效果
1. 项目背景¶
写法要求同论文，约3页，写的都是大项目
1.1 项目背景及意义（类似开题）
1.2 项目内容
- 注意不要写成“目标与任务”，是已经完成的
- 注意点睛：本文作者的主要贡献是……
1.3 本文结构
- 务必点睛：本文作者的主要工作在……
2. 产品架构概述¶
不超过1/3篇幅，注意标题要换成你的项目
2.1 项目整体需求概述
- 1-3页，其中哪部分需求是由你解决的（比如开题有12页来讲需求，把他浓缩成两三页）
2.2 项目整体系统结构（配图）
- 其中哪个模块是你完成的
2.3 关键技术分析
- 所有你在实现中用到的、不是你发明的技术[引文]（不可能有大量关键技术，三个左右比较合适，学校没有开课的技术
- 写清楚为什么选用这个技术，而不是其它（为什么用这个数据库不用那个数据库）
3. 你的工作¶
《第3章－第x章 你的主要工作》（重点，超过1/2篇幅）
- 你负责的模块的需求分析（一个模块来说需求1页左右即可）
- 你负责的模块的架构设计
- 最有技术难度的实现细节
常见问题
- 只写做了什么，不写为什么
- 正文贴大量源代码（伪代码，流程图）
4. 测试及成果展示¶
《第x+1章 测试及成果展示》 - 测试目标（要验证什么指标） - 功能测试：完整的交互流程全部要走一遍 - 性能测试：webrunner
- 测试策略（打算怎么测）
- 测试结果与分析（附部分重要界面截图等）
常见问题
- 海量截图灌水
- 只有数据没有分析
5. 总结与展望¶
写法要求同论文，《最后一章 总结与展望》
- 总结全文成果
- 展望可以进一步改进的工作
常见问题 - 重复第一章内容 - 展望暴露当前工作不足 - 过分夸张的结论
毕业论文¶
0. 摘要（同设计报告）¶
1. 绪论¶
1.1 课题背景及意义（类似开题）（introduction）
1.2 研究现状及本文贡献（related works+conclusion）
- 是文献综述的缩写
- 务必点睛：本文作者的主要贡献是……，提出了 解决了/改进了/完成了
1.3本文结构
- 务必点睛：本文作者的主要工作在……
2. 基础理论综述¶
不是related works，不超过1/3篇幅，小论文不需要这个部分
问题>假设>实验>结果>分析 的过程中的使用的理论
- 注意标题要换成你所讨论的理论
- 描述你将要用到的、不是你自己提出的理论和算法［引文］
- 为什么你后面会用它解决问题？而不是用另外一种算法?
- 不是文献综述，（不是继承自的工作，那是1.2，你自己在工作中的使用到的理论是这一部分的内容）
3. 你的工作¶
《第3章－第x章 你的主要工作》 重点，超过1/2篇幅
- 将第2章描述的理论应用于具体课题，解决具体问题的方法
- 详细描述算法的推导过程，为什么这样做是对的
- 用伪码和图描述算法流程
4. 测试与分析（同设计报告）¶
5. 总结与展望（同设计报告）¶
课内讨论8：评价毕业论文
科研论文¶
- 反映科学客观事实，不是反映作者水平（写给同行看，不再是学生）
- 选题新、方法新、资料新（强调说明自己工作与前人之不同）
-
写论文的前提
- 确实有了好想法，不要为写而写
- 确实取得了有价值的结果，对学术界有贡献
- 实验可重复，经得起检验
- 有必要昭告天下
-
常见问题
- “贡献”罗列太多，亮点不突出
- 滥用“革命性”！“突破性”！“史无前例”！
- 太多数学、理论、公式，恶意秀智商
- 大量引用自己的论文
Introduction 套路¶
- 本课题如何重要
- 前人A、B、C……研究过，提出了什么方案，有什么问题（简短一句话概括）
- 我们提出了方法X
- X的特点，与A、B、C……的不同
- 实验证明X比A、B、C……优越
- 本文的结构大纲
Related Work¶
- 将前人的工作分类
- 对前人工作简短描述（几句话到位）
- 与自己的X算法比较
请公正评价前人的工作 最好举出各自适用的例子
Poster¶
是学术会议的一个重要组成部分，是对口头报告的重要补充。特别是为新入学术圈的研究生们提供一个展示才华和锻炼的机会
什么是好的Poster
- 学术水平高：有创新，工作扎实
- 美观（带本校和会议的logo）
- 有讲解
- 有补充展示的实物更好（比如借台电视放实验录像…）
个人作业：针对给定的开题报告、毕业设计报告、毕业论文各一篇，分别批评其内容组织方面的缺陷，给出第一稿的修改建议。要求交一份修改建议，而不是在原稿上做修改标记！（第几页第几行有什么问题要怎么修改
开题报告
本文总阅读量次