技术文档

如何写好技术文档?

作者:admin   来源:未知

  行为一个曾以超精确文档而遭人白眼的交互安排职员,我最大的败笔,正在于写文档只正在乎自身有没有功效感,而不是别人看不看得懂、能不行顺手领会,后果是,文档虽全,但没人有耐心绪解消化,末了仍然都跑来问我,不堪其烦。

  。别帮衬着文档漂后、布局明了,而去问看文档的人,这么写能不行看懂,用什么体例写更容易懂,哪些地方不必太精确,哪些地方要多说几句。

  倘若还处于做不厚的情形,就仍然先老诚实实有一句写一句吧, MECE 准绳、金字塔道理是根本功。

  我正在卡内基梅隆大学这学期学一门课software documentation,基于group project和课上的少许体验,约略说一说,期望能有点儿帮帮:做software doc的话,自身要对产物先由编造的分析,料理出product profile框架要举行posona,用户筑模,分析自身的用户,明了你的读者是哪些人,他们的需求是什么,教学水准怎样,tech布景基本怎样,等等,基于此你明了文档要蕴涵哪些实质,哪些部门要精确,哪些要弱化,道话要用怎么的气概自身去用软件,器重自身第一次的产物体验,那黑白常贵重的,记实下来你遇到题目的地方,这些或者要放到troubleshooting内里,必然眷注首次用户体验疏导疏导疏导:大凡手艺文档的话,正在表洋都是幼组合营完毕,和你的组员举行筹商疏导,造成初期的文档框架和实质;和developer疏导,分析产物的少许潜正在性能,分析少许研发部分期望用户操纵的性能等等;和市集部分疏导,分析他们念要重要marketing的产物特质、他们期望用户眷注的性能,正在修建文档的时辰加强。

  以上约略是写的部门上,那么说说手艺文档写作必要具备的少许才气吧:道话,这个不必多说了,英语中文的写作才气,闭节是能不行把话说得简明、明了、顺畅安排才气,这重要说新闻安排,大数据时间夸大新闻安排的才气啊(这是我的一个国内的UI先生告诉我的),我正在美国也学这方面的东西,做安排,做文档都是必要新闻架构,新闻安排的,若何把新闻宗旨了解的摆列和发现,让文档reader-friendly,这是一个值得一直思量的题目懂点儿手艺,最少有technical aptitude,我正在美国和salesforce technical writing部分的senior manager闲谈时辰他说的,文档工程师不必然要会编代码之类的,不过最少要有对科技的有趣,要有能处分庞杂题目的才气和恒心。

  我有十多年开荒体验,文科连续很好(正在上海最好的中学英语语文都拿过年级第一名),从幼热爱文学,手不释卷.我应有资历道道这个话题。

  与其古板妙技,不如从底子出手,进步片面涵养和智力.也即是从阅读先河,读一流作品多了,天然明了怎样写。

  中国大陆解放后语文教材有许多二三流的东西,容易误导年青人表国作品好一点,翻译因懂英文,本质已高于大凡人。

  古典作品历程史乘磨练,需专业常识少.中国大陆的特色是解放后最好的中文作者都下放去做翻译了,因而又多了一重质地包管.这些老头老太翻译的平常是古典作品。

  文件排版以专业东西措置, 如现正在时髦的markdown.不该当把时分糟塌正在排版上,让东西行止理。

  比来做完一个项目,好好的料理了一下文档。我觉的,写手艺文档,可能料理自身的思绪,对这个项目中的常识点,要知其然,更要知其因而然。写文档,起首是要明了这个文档的大旨,重要说清爽一个什么题目。一篇文档倘若要涉及多个题目的话,最好先分袂扼要先容一下,然后另写一篇较精确的文档,来添加被援用的文档,如此下来,每篇文档都各有所专,思绪的话可能明了一点。

  正在写文档时,要集合项宗旨需乞降约略的完成流程,最好是贴图来说明少许对比难领会的地方,有图有注解,如此更好领会。对付文档中,自身以为对比厉重的地方,必要用赤色符号出来,如此让看的人有要点。

  看过公司的典型文档,上面章节,修订记实,主意眷注,页眉页脚都很正道,末了的附录适可而止,并且都是pdf版的。倡议先把文档写出来,给不分析这个文档大旨的人审查,看看他能领会个约略不?倘若不行,询查见地而且做二次批改。文档的实质正在援用网上原料的同时,要融入自身的思量,集合项目必要,提炼自身的核心句,让别人看的话,一针见血。

  倘若自身觉的很疾意了,就把doc式样转成pdf式样的,然后再颁布到共享中去,我老是觉的,doc式样的即是没有pdf式样的看得爽。

  闭于手艺写作的书许多,手艺写作专业身世的同事也曾保举过的一本叫《Technical Communication》,目前依然出到第十版了。

  相对来说ppt体例的文档对比受接待,只是也别弄太长。哪怕唯有四五页的word文档也让人望而却步不念看。

  1. 弄清读者是谁:给最终用户(幼白)的、给编造爱护职员、给其后的手艺职员移交的的文档确信不雷同,给幼白的重截屏,给爱护的重操作,移交的重道理。

  2. 切换“愚笨者”形式:许多东西是正在做项宗旨进程中试错蕴蓄堆积出来的。做着做着:这么干从来不成啊,该当如此如此,改安排!做着做着:哎呀,从来有这个题目没有商讨到,现正在加进去,改安排!做着做着:哦?什么?客户要改需求?好吧,我改安排!如此下来大型的IT项目做到末了,和最先河的安排依然截然不同了,依照从来安排的思绪来写文档确信是不成的,依照时分秩序把批改加上会越发庞杂。写文档的时辰必要切换到“愚笨者”形式,把自身设念成一个刚才承受项目要先河安排的人,面临已知的这些“新央求”和敌手艺全新的领会,从头写一份文档,如此才干脉络明了,可读性高。

  3. 从命尺度构架:大型项目牵涉的东西多,有实质的摆设有虚的观点,有效户界面也相闭键性筑设,杂七杂八什么都有,倘若不依照一个尺度构架来写文档,很容易就眉毛胡子一把抓。这时辰就必然要找一个尺度构架,比方OSI七层构架,TCP-IP四层构架等等,从上到下或者从下到上,写着也简单,看着也顺心。

  无论是正在国内上《英语手艺写作》课程仍然正在荷兰上 Hans Van der Meij 和 Menno De Jong 先生的手艺传扬干系课程,都指出了对付主意读者判辨的厉重性。

  大大都手艺写作职员都邑犯如此的毛病:念当然以为全数读者都雷同或者全数读者都跟自身雷同。这也是很多怒放职员写出来的文档读者看不懂的情由之一,对读者领会不敷,少许认为读者懂的常识,原本读者底子不领会。设念中的读者能做到的或者所喜爱的,跟实质考察出来的往往不是一回事。仅靠写作职员的主观体验和领会写出来的文档,预计也没有多罕用户会锺爱。念念追个心仪对象,也必要挖空心机搞清爽人家的喜爱和布景,再投其所好,才有或者获胜。更别说咱们还念要让用户从口袋里掏钱来买你写的东西,不去判辨需求,满意其口胃,若何或者获胜呢?因而说,熟行动写作之前,更厉重的是搞清爽自身的主意读者是谁?他们有什么样的需乞降布景常识?.....对付特定的主意用户群明白于胸,写作起来才干拿捏好难易程,不至于赘述或者过于简化。

  事理很浅薄,不过履行起来就没那么简陋了。由于判辨主意用户耗时吃力,有时霸占了全面写作周期的一半时分以上。产出与结余有没有直接明明的干系。加上国内手艺写作行业历来就方兴未,对付这种用钱不过有没有直给与益的措施,天然即是能省则省。只是,我念这并不会永恒。由于,正在西方,文档事务家即是花洪量时分去商量自身的用户。此表,就算目前的前提分歧意,也不代表无计可施。例如说,可能看用户判辨讲述,跟产物司理研讨用户需求,更好的即是直接出席用户需求判辨,或者找契合前提的亲友深交充任被试。手段老是有的,闭节是有没有这个认识。

  IBM中国ID团队的《Information Development》这门课刚才把重要实质讲完,又有少许简历、邮件等等的写法没有讲。

  像IBM、微软这些公司,固然作为相较于少许互联网公司有些慢,不过文档写具体实看上去就比别人品调要高少许,情由或者重要是他们有特意的团队去做这件工作,再者面向企业的生意对比多,而这些生意的庞杂性也要比消费级的生意大,因而写好文档就存正在于全面公司的基因内里了。对付片面来说倘若对TW感有趣到这些至公司做专业的文档写作事务也是不错的,倘若是措施员的话有如此一个文档的认识,行为full stack的一部门,肯定也是不错的。据先生先容,表洋像CMU等等高校依然有手艺文档开荒这个专业了,而国内的话除了有少许像这种手艺英语写作之类的课程,并没有成编造的作育计划。

  那这些重要生意面向企业的科技公司为什么要写手艺文档呢?家喻户晓的是,现正在面向平淡消费者的智能摆设UI的安排正正在变得越来越傻瓜化直觉化,纵然是幼孩子也可能正在很短的时分内上手,不过对付企业级的产物,往往都是GUI绝顶庞杂以至没有GUI唯有号召行界面的,这就形成了IT从业职员(措施员、Administer)不或者正在拿到产物之后就凭感想直接先河用,跟咱们平居的大大都产物雷同,软件的仿单(Instruction)就必不行少了,当然,这里就指的是手艺文档。也许有一天跟着人机交互的进展,企业级产物也可能以更好的格式安顿和操纵,到那时手艺文档或者手艺文档开荒这个地位也将磨灭吧,但正在那之前或者自以为产物还没有做到可能没有文档就可能全体上手,仍然老诚实实写好文档。

  Developing Quality Technical Information (豆瓣)?。

  鲜枣教室自从2017年5月先河正式创立,迄今已有3年多的时分。这一岁月,咱们的实质连续都对峙以手艺类科普著作为主,输出了约莫400多篇原创。此中绝大部门,都是我写的。

  我的念法对比简陋,即是期望不妨输出平凡易懂的手艺科普著作,让手艺不再平板,帮帮更多人(加倍是即将进入行业的年青人)分析通讯,分析5G、物联网、云计划和大数据如此的ICT界限前沿科技常识。

  绝顶幸运的是,鲜枣教室的实质受到了专家的接待,获得了珍贵的认同,也蕴蓄堆积了越来越大的影响力。咱们现正在依然渐渐成为行业里排名前线的手艺类实质原创自媒体。

  我也曾正在某摆设商做了四年的手艺扶帮(此中三年海表),蕴蓄堆积了雄厚的通讯产物手艺常识和推行体验。然后,又做了三年的文档司理,蕴蓄堆积了洪量的文档写作、文档编造创办、文档质地解决方面的体验。末了,又做了四五年的培训司理,练习怎样举行高效的实质表达、怎样针对表里部客户举行常识通报。

  加倍是手艺文档写作这一块,我从刚入职就养成了体验唾手总结、手艺按期蕴蓄堆积的平居写作民俗,并维系至今,可能说是受益匪浅。

  文档,不管是对付员工片面,仍然对付企业,都有绝顶厉重的事理。对付手艺类公司来说,手艺文档的厉重性更是不问可知。它的价钱,全体可能等同于产物自己。或者说,手艺文档即是产物的一个厉重构成部门。

  文档的底子本质,是贯穿产物性命周期的重淀蕴蓄堆积输出物,是新闻通报的厉重东西和载体。分歧阶段的文档,有分歧的影响。分歧的岗亭,有分歧的文档编造。

  正在产物安排和研发阶段,有产物安排引导书、产物性能需求仿单等。正在产物工程交付阶段,有版本颁布申明、手艺引导书、升级/割接/扩容引导书等。

  文档还分为内部文档和表部文档。内部文档任职于内部用户,表部文档任职于客户、合营方等表部用户。表里部文档密级分歧,实质会有所删减,表述格式和侧要点也会有所分歧。

  文档用于引导实质事务。文档质地的长短,会影响新闻通报具体切性和效能,进而影响事务的完毕、项宗旨交付。

  比方,产物开明文档太烂,客户看不懂,合营方员工看不懂,以至自身的工程师也看不懂,就无法遵循文档获胜完毕摆设开明或升级割接。文档倘若崭露毛病,以至或者形成要紧的事情。

  现正在市集逐鹿越来越激烈。有时辰,固然产物自己做得很好,价值也很有上风,不过文档太烂,雷同会被客户渺视,进而拉低了产物的团体逐鹿力。有损公司品牌形势。

  起首,必要设立筑设一个美满的文档解决编造,囊括文档架构编造,文档职责归属,文档立项、开荒、评审、颁布、归档流程以及对应平台等。

  早期的时辰,国内许多企业应用人力本钱上风,创议人海兵书,将资源聚积参加到产物研发上,靠价值上风和版本速率(需求反映速率)抢占市集。

  开荒工程师忙着写代码,做版本,哪有时分去写文档?根本上都是拿产物安排引导书改一改,截截图,就扔给了售后,以至扔给了客户。

  内部用户(售后)骂娘,指挥原本心坎少见,真相资源有限,只可断送文档保版本,对内部反应举行。而表部客户的见地,是无法举行的。

  对付少许低端客户来说,对比眷注的是价值。绝顶的本钱上风,可能让客户粗心文档。不过,对付高端用户来说,他们对文档的央求和对产物的央求是划一的。没有精良齐套的文档,雷同不给中标。

  于是,倒逼摆设商参加资源补齐短板,结构人力举行文档专项开荒。结果出现,原本并不是写不出好文档,而是之前没有舍得参加资源。

  然而,一朝项目应付过去,资源又会撤走,好禁止易设立筑设起来的文档质地,又再次垮塌,如斯恶性轮回。

  因而说,对付企业,念要把文档疾意度搞好,设置有利于产物品牌的文档品牌形势,闭节正在于指挥愿不承诺投钱。有钱就有人有资源,这是搞好文档的根本条件。

  跟着市集的典型和成熟,加上逐鹿日趋激烈,文档的厉重性一直擢升,越来越多的企业职掌人先河认识到这个题目,一直加大对文档的资源参加。

  前面说的文档解决编造,是有一整套技巧论的。大到文档编造的架构(事实必要多少篇文档,分袂由谁来职掌,写给谁看),幼到文档实质的编写,都有相应的表面和妙技。这些不是靠人海兵书就可能完善完毕的。

  念要写好一篇文档,起首第一个题目,即是你要搞清爽这篇文档的定位——它是一篇什么本质的文档?写作宗旨是什么?它的操纵者是谁?

  比方我时常写的零基本初学,定位即是对干系实质布景常识毫无分析的读者。然而,又不是幼学生那种宗旨,而是起码依然完毕了基本教学,处于大一及以上学历水准的读者,有根本的物理学和数学常识,也有对天然现场的根本认知,又有寻常人的逻辑思想才气。

  倘若你写手艺文档,起首要搞领会,文档操纵者是内部客户仍然表部客户,是有体验的客户,仍然零基本的客户,是依然阅读过前置文档的客户,仍然第一次看这套文档的客户。

  明了了对象之后,要切记,正在写作整篇文档的进程中,你都要随时切换本身脚色。必然要站正在读者的角度,琢磨文档实质是不是能看得懂。

  大部别离艺文档的作家不是作者,以至不是文科生,而是手艺工程师。这类人正在文字表达妙技上平常对比缺陷,不过有一个明显上风,那即是逻辑思想才气强。对付写作来说,这一点绝顶厉重。加倍是手艺文档的写作,务必有很强的逻辑思想才气。

  文档的总体布局,必必要有逻辑连贯的章节秩序。文档的语句,也务必有逻辑厉谨的表述格式。过于跳跃的思想,不适合操纵于手艺类文档。文科生过于感性的文字,也不适合手艺类文档。

  手艺工程师最常犯的瑕玷,即是刚愎自用:“这么简陋,你若何都不懂?”“这是基本啊,是片面都懂!”然后就偷工减料,三言两语,跳过了洪量的细节,粗心了或者崭露的不怜惜况,让文档操纵者不知所措。以至有的作家,锺爱玩“哲学”,感到越写得高妙,就越显得自身很懂,具体好笑。

  全部的操作环节,固然简短,但实质异常明了,分为几个环节,每一个环节敲什么号召、有什么宗旨,都邑告诉你。

  正在末了,还会有验证结果闭节(本例的验证结果部门相对简单,实质上还该当囊括通过号召,查看结果,以此举行明了验证)。

  以前咱们常说,中式菜谱锺爱用“盐少许、酱油少许、大火煎炸瞬息”这种定量绝顶吞吐的表达格式,原本确实和咱们的写作民俗有必然干系。对付手艺文档来说,咱们这方面的侧重性作育和演练确实做得不敷。真正的写作,不是卖力探索辞藻的都丽,而是兴趣和情境具体切表达。

  所谓“字不如表、表不如图”。手艺是很笼统的东西,也是领会起来很有难度的东西。念要靠纯文字举行实质转述,是很穷苦的。因而,该当更多地借帮表格和图片,以至gif动图,帮帮读者领会。

  说白了,这个即是磨练作家的义务心。倘若写作家不行站正在读者的角度,不行以读者疾意度为起点,那么,就不会承诺节表生枝去绘图。绘图是很庞杂的事务,有时辰我写著作,一幅图都要画一天,很禁止易。

  养成并对峙写作的民俗,有利于作育逻辑思想才气,也有利于片面常识重淀蕴蓄堆积。片面可能开手艺blog或公家号,公告并分享自身的体验心得,会很有功效感,日积月累的话,以至或者造成片面品牌和影响力,有利于自身的职业生活进展。

  固然现正在视频化的趋向明明,不过我片面以为,文档是无法被视频代替的。目前的手艺,视频无法举行迅疾实质检索,无法举行迅疾更新和批改,无法举行迅疾通报,文献体积较大,这些都决心了文档的不行取代性。

  视频的上风,更多正在于实质形势而灵敏的呈现,可能让用户有更感性的领会,更深入的追忆,适合培训,不适合事务查阅,不适合归档。

技术文档

联系我们

CONTACT US

联系人:张先生

手机:13988889999

电话:020-66889888

邮箱:admin@baidu.com

地址:广东省广州市番禺经济开发区58号