《技术写作实用教程》写作说明

作业要求

  1. 每人认领 “技术写作从业能力要求” 的一个章节;

  2. 写作前阅读课程课件、自己的学习笔记、其他相关教程和论文;

  3. 拟定写作内容的提纲,可以是思维导图或Excel表的形式,然后约时间与老师讨论,初步明确写作内容后即可上手写作,后续依然可以动态调整;

  4. 使用DITA语言写作,写作工具不限(oXygen, XMLMind,Codex)都可以,写作后提交全部的dita工程文件,用于后续PDF和webhelp的发布;

  5. 写作之前,参照教 “教材写作风格指南” 的规定(如截图尺寸,文件名命名方式等);

  6. 提交方式:课堂派,截止日期 2022年1月25日 17:00;

注解

期待大家的作品!

有问题请随时和我联系。微信或邮箱均可。

为什么写这本教程

教学相长

写这本书最核心的目的,还是让大家将本学期所学内容系统性地整理与回顾一遍。平时授课,因为时间有限,不少内容只能蜻蜓点水过一遍,大家可以利用寒假时间,就自己感兴趣的话题深入探究一下。一种增加自己对某个知识了解的方法,就是去尝试教别人,在教授的过程中,你的各种准备会促使你深入学习某个知识,在讲解的过程中你会发现很多自己原来没有意识到的视角,这又会进一步拓宽自己的知识面。

本书要求大家使用DITA创作,这个过程又能增加大家对DITA标记的了解,同时我们使用 Docs as Code 的模式,过程中会用到很多新技术来确保教材的质量,相信这一创新型的写作模式,会让大家有很多新的收获。

填补空白

目前我国市面上还没有中文的技术写作教程,已经发行的几本技术写作教程都是英文的,而且更多的偏向实用写作或一般性介绍,我们这本书将可以弥补这一不足,我们以中文写作,面向应用,读者将能学习到入门技术写作行业所需的必要知识。这本书将能大大推动技术写作在我国的发展,为国家培养更多的技术写作人才,同时高质量的技术信息又可以反哺我们的研发体系,促进国家的工业化进程。

教程的特色

图书完成后,将会有如下创新:

开源

这本书将会是开源的(遵循 The Creative Commons Attribution-NonCommercial 4.0 Unported License 协议),未来的读者可以自由的使用本教材进行学习,学生或拟转行做技术写作的同学,均能以此为基石。

活教材

对教材的刻板印象,就是出版社制作的书籍,对于大部分人来说,从写作到发行,如果没有出版社的协助,是比较困难的。当下,大部分作者用Word写作,写作后由出版社请美工排版,最后印刷后供读者购买使用。整个过程太长,极端情况下内容刚出版就已经过时了。我们目前尝试使用技术写作的工具链,大家可以使用所学知识,完成数字出版,而且教材可以边写边用,并能即时将读者的反馈更新到教程中,让教程一直保持旺盛的生命力。

大家可以DIY一切,自己动手丰衣足食。其实教材本来就是作者和读者的事情,完全没有必要通过出版社,这个模式说不定可以给未来的其他老师提供一些新思路。

同侪写作

这一本由学生写给学生 (by students for students),由学生进行同侪校阅 (Peer Review)的图书。本班同学,既自己创作又校阅他人书稿,一边输出知识,一边学习其他同学的知识。