精华内容
下载资源
问答
  • 怎么写好技术文档
    千次阅读
    2019-05-09 14:34:03

    写在前面:
    我也没想到我的第一篇正式的技术博客会是关于怎么写文档的。因为最近在实习,刚好,师姐让我写一篇文档。然后,作为小白的我当然第一版写的乱七八糟。后来,师姐给了一个方向。然后,我模模糊糊的get到了什么。后来,我就开始去查,然后阅读了很多人的博客and书籍。花了大概几个小时的时间去想明白到底该怎么写文档。其实这些点并没有难度上的要求,难得是当你准备写文档的时候,这几个准则始终记在心里。

    第一点:这是很多人的共识,先明确你的写作对象。

    我记得我第一份实习的时候,我召开了一个代码的review会议。然后,我们老大对我的代码提的要求在我看来很奇怪。后来,我和带我的师兄聊了一下。他说,因为我们上次聊这个问题的时候进展到那里。所以,他对于这个事情的记忆一直停留在那个节点。所以,后面我们的讨论他都不知道,所以说的和我现在的东西对不上也就可以理解了。
    你看,即使是同一个部门和你的业务密切相关的人,老大和天天带你的师兄都是两个完全不同的读者。所以,如果你不明确你的读者,你的文档的可读性就完全没法保证。因为可读性不是由你来评判的,而是由你的读者来评判。

    第二点:确定写作目标

    你写这篇文章是为了向你的读者传达什么信息。这是你要明确的目标。如果写作目标都不明确,那你的文档即使写出来,因为没有重点,也可能被人弃之不读。如果你不想出现这种情况,那还是最好在动笔前,先把写作目的写在开头,等到文章全部写完之后,对着写作目标再看一遍文章。如果没问题,删掉写作目的,文章完成。

    第三点:确定文章结构

    我知道搜到这篇文章的人大都是因为:我没有思路,我不知道该怎么写,大脑一片空白。以下两种方式或许对于你的行文有所帮助

    1.总分(总)

    我知道这是小学作文里都会用的套路。但是,it works。对了,比较专业一点的说法是叫做金字塔原理
    金字塔原理:
    中心思想1
    1. 支撑观点
    2. 支撑观点
    3. 支撑观点
    中心思想2
    1. 支撑观点
    2. 支撑观点
    3. 支撑观点
    中心思想3
    1. 支撑观点
    2. 支撑观点
    3. 支撑观点
    参考前面的写作目的,你大可以把你的结论放在文章的开头,然后,从几个方面找些论点以及证据来支撑你的结论,最终以期说服你的同事,主管,业务伙伴。

    2.MECE原则

    MECE原则其实就两条:
    完整性:保证一个项目被分解的完整,没有漏掉某些项目。
    独立性:强调每项工作之间要独立,每项工作之间不能有交叉。
    但是,把一个具体的问题按照这两个原则进行分割并不容易,下面我举一个我的例子,希望对读者有所帮助。
    eg:
    在写文章之初,我也是大脑一片空白,直到一个公式突然出现在我的脑海里,结合上MECE原则,然后整个文章的结构就都有了。
    这个公式就是:
    程序=算法+数据结构
    没错就是绝大多数计算机类的教科书第一章甚至引言都会出现的公式!
    所以,我的idea是,既然我要针对一个程序进行说明,那么我就拆分成,对算法的说明以及对数据结构的说明。用了哪些数据结构,分别是怎么实现的。用了哪些算法,分别是怎么实现的。按照这个思路,我很快列出了,我要说明的数据结构以及算法。然后很快写出了文档。
    最后,师姐给的回复是:结构没问题,个别语句不清晰。就这样作为一个从没学过怎么写技术文档的我,成功的写出了一篇技术文档~
    写在最后:在查资料的时候,发现外国的大学已经有专门的技术文档专业了。而我国类似的课程可能只在部分顶尖大学刚刚开始。这从一个侧面说明,追赶的路上道阻且长,与诸君共勉~

    更多相关内容
  • Winpcap中文技术文档

    热门讨论 2012-09-21 07:19:26
    Winpcap中文技术文档,内容包括: 1)Winpcap技术文档; 2)Winpcap教程 3)Winpcap核心资源 4)远程包捕获
  • 如何写好技术文档——来自Google十多年的文档经验

    千次阅读 多人点赞 2021-07-25 09:24:20
    如何产出高质量文档像管理代码一样管理文档明确你的读者是谁清晰的分类参考文档设计文档引导类文档概念性文档Landing pages(落地页)文档Review写文档的哲学5W法则三段式写作结语 本文大部分内容翻译总结自...

    本文大部分内容翻译总结自《Software Engineering at Google》 第10章节 Documentation。 另外,该书电子版近日已经可以免费下载了 https://abseil.io/resources/swe_at_google.2.pdf,有兴趣的同学可以下载翻阅下。 首先声明,本问所说的文档不仅限于纯文本文档,还包含代码注释(注释也是一种特殊形式的文档)

    在这里插入图片描述
    很多技术人自己非常轻视技术文档的书写,然而又时常抱怨文档不完善、质量差、更新不及时…… 这种在程序猿间普遍存在的矛盾甚至已经演变成了一个段子。
    在这里插入图片描述

    文档的重要性

    高质量的文档对于一个组织或团队来说有非常多的益处,比如让代码和API更容易理解、错误更少;让团队成员更专注于目标;也可以让一些手工操作更容易;另外如果有新成员加入的话有文档也会让他们更快融入……

    写文档有比较严重的收益滞后性,不像测试,你跑一个测试case,它能立即告诉你是对还是错,它的价值马上就体现出来了。而写一份文档,随着时间的推移,它的价值才会逐渐体现出来。 你可能只写一次文档,将来它会被阅读上百次、上千次,因为一份好的文档可以在未来替你向别人回答类似下面这些问题。

    1. 为什么当时是这么决策的?
    2. 为什么代码是这样实现的?
    3. 这个项目里都有哪些概念?
    4. ……

    写文档同样对于写作者也有非常大的收益:

    • 帮你构思规范化API: 写文档的过程也是你审视你API的过程,写文档时会让你思考你API设计是否合理,考虑是否周全。如果你没法用语言将API描述出来,那么说明你当前的API设计是不合理的。
    • 文档也是代码的另一种展现: 比如你两年后回过头来看你写过的代码,如果有注释和文档,你可以很快速理解代码。
    • 让你的代码看起来更专业: 我们都有个感觉,只要文档齐全的API都是设计良好的API,虽然这个感觉并不完全正确,但这两者确实是强相关的,所以在很多人眼里,文档的完善度也成为衡量一个产品专业度的指标。
    • 避免被重复的问题打扰: 有些问题你只需要写在文档里,这样有人来问你的时候你就可以让他直接去看文档了,而不是又给他解释一遍。

    为什么大多数人都不喜欢写文档?

    关于文档的重要性,每个技术人或多或少都知道一些,但很多人还是没有写文档的习惯,为什么? 除了上文中提到的文档的收益滞后性外,还有以下几点原因:

    • 很多工程师习惯将写代码和写作割裂开,不仅仅是在工作上,而且在思想上就认为它们是完全不相关的两项工作,这就导致好多人重代码不重文档。
    • 也有很多工程师认为自己不善写作,索性就不写了。 这实际是个偷懒的借口,写文档不需要华丽的辞藻、生动的语言,你只需要将问题讲清楚即可。
    • 有时候工具不好用也会影响的文档写作。如果没有一个很好的写作工具将写文档嵌入到开发工作流程中的话,写作确实会增加工作的负担。
    • 大多数人将写文档看做是工作的额外负担。 我代码都没时间写,哪有时间写文档!,这其实是错误的观念,文档虽然前期有投入,但能让你代码的后期维护成本大幅降低,磨刀不误砍柴工这个道理相信大家都还是能理解的。

    如何产出高质量文档

    既然理解了好文档的重要性,我们如何保证在时间的长河中维护好一份文档,这里有些相关的方法论,大家可以参考下。

    像管理代码一样管理文档

    对于如何写出好代码,整个技术圈已经有好多经验的总结了,比如书籍《重构》《代码简洁之道》…… 针对各种编程语言,也有相关的规范,比如国外的Google C++规范,国内的阿里Java开发规范等…… 但对于文档 似乎相关的资料却很少。但实际上,不应该把文档和代码割裂开来,你可以简单粗暴地认为文档其实就是用一种特殊语言书写的代码,这种语言就是人类的语言。这么想的话,实际上我们很多在代码和工程中总结出来的经验,也可以直接用在文档中,比如:

    • 有统一的规范
    • 有版本控制
    • 有明确的责任人维护
    • 有变更Review机制
    • 有问题的反馈和更新机制
    • 定期更新
    • 有衡量的指标(比如准确性,时效性)

    明确你的读者是谁

    写文档有一个很常见的错误,那就是很多人文档都是写给自己看的,这种情况下就会导致你的文档只有自己或者和你有相似知识背景的人才能看懂,团队较小时这种问题还好,你们都做着类似的工作,所以也都能看懂文档。但当团队逐渐壮大后,问题就会凸显出来,新人有时候有着和你不同的工作背景,甚至现在都做着不同的工作内容,这时候你之前写的文档他们就很难读懂了。

    所以在写文档之前请明确你文档可能的读者会是哪些人,然后针对他们的特点着重关注如何才能让他们理解。当然,文档也不一定要非常严肃和完美,只要能向你潜在的读者说明问题即可。 记住文档是写给别人看的,不是给自己看的。

    根据专业水平可以大致将读者分为三种 新手、老手和专家,针对不同水平的人写作需要有侧重点。比如针对新手,你需要重点介绍下里面涉及到的术语和概念,然后详细讲解具体的的实现。相反,针对专家 你可以省去这些额外的信息。注意,这里没有严格的标准,因为有些文章新手会看,专家也会看, 这里还是需要具体情况具体分析。

    另外一种对读者分类的方式就是根据读者阅读文档的目的来分类,比如有人知道自己遇到了什么问题,就是来找解决方案的。还有一批人只有一个简单的想法,但不知道具体的问题。举个例子,以读数据库慢为例,前者已经知道数据库慢可能是因为数据量巨大且没有加索引,解决方案很简单 加索引,这时候他可能需要知道的是如何正确地加索引。而后者可能着重关注的是为什么读数据库会慢,这时候你可能需要额外重点介绍下数据库相关的原理。

    清晰的分类

    文档大致可以分为以下几种类型,每种类型也有自己不同的特点和写作侧重点。

    参考文档

    参考文档也是大部分开发人员日常会使用和书写的文档,比如我们使用某个框架或者工具,都会有API说明文档,这就属于参考类文档。 它并没有太多的要求,只要能向读者展示清楚如何使用即可,但无需向读者讲明具体的实现。

    注:参考文档并不仅限于API文档,还包括文件注释、类注释、方法注释,要求都是能准确说明其用法。

    设计文档

    很多公司或者团队在项目开始前都要求有设计文档,设计是项目实施的第一步,所以在设计文档书写的过程中要求尽可能考虑周全,例如该项目的存储、交互、隐私……

    好的设计文档应该包含以下几个部分:

    1. 设计目标
    2. 实现的策略
    3. 各种利弊权衡和具体决策
    4. 替代方案
    5. 各种方案的优缺点

    写设计文档的过程也你对整个项目做规划、思考可能出现问题的过程,设计的越详细、思考的越多,未来遇到问题的可能性就会越小。

    引导类文档

    引导类文档也很常见,一般都是Step by Step的形式。比如我们在使用某个框架或者工具的时候,一般都会有个引导类的文档一步一步帮助你快速上手。 大家写引导类文章大家非常容易犯的一个错误就是预设了很多背景知识。 一般使用文档都是有开发者写的,他们都非常了解这个工具的相关的知识,所以习惯性的会认为,啊 这个知识点很简单 用户也肯定会吧,实际上用户不一定会。这本质上就是一种认知偏差,这种现象在跨团队协作 尤其是多端协作的时候也非常明显。

    这类型的文档写作中,要求写作者尽可能站在用户的视角上思考,极力避免出现和用户的认知偏差,力争每个步骤做到明确无歧义,每两个步骤之间做到紧密衔接。

    概念性文档

    当参考文档无法解释清楚某些东西的时候,就需要概念性文档了,比如某个API的具体实现原理。其主要是为了扩充参考文档,而不是替代参考文档。有时候这和参考文档会有些内容重复,但主要还是为了更深层次的说明某些问题、解释清楚某个概念。

    概念性文档也是所有文档中写作最难的,也是被阅读最少的,所以很多情况下工程师最容易忽视。而且还有另外一个问题,没合适的地方放,参考文档可以写代码里,落地页可以写项目主页里,概念性文档似乎也只能在项目文档里找个不起眼的角落存放了。

    这类文档的受众会比较广,专家和新手都会去看。另外,它需要强调概念清晰明了,因此可能会牺牲完整性(可以由参考文档补齐),也有可能会牺牲准确性,这不是说一定要牺牲准确性,只是应当分清主次,不重要的就没必要说了。

    Landing pages(落地页)

    Landing pages就先简单翻译成落地页了,没想到啥恰当的翻译词。比如一个团队或者项目的导航页,虽然没啥具体的内容,但应该包含其他页面的链接。 比如你新入职一个团队,比较成熟的团队都会扔给你一个文档,这个文档里包含常用的工具、文档链接,这就是这个团队的落地页。
    落地页的问题就是随着时间的推移,页面可能会变的越来越乱,而且有些内容会失效,不过这些问题都好解决,做好定期的维护和整理就行。
    落地页的技术难度不高,但要求内容的有效性、完整性和分类清晰。

    文档Review

    在一个组织内,光靠个人去维护文档是不行的,必须得借助群体的智慧。在一个组织内部,文档的变更也应该像代码的变更一样,需要被其他人Review,以提前发现其中的问题并提升文档的质量。

    如何Review文档:

    • 专业的视角来保证准确性: 一般由团队里比较资深的人负责,他们关注的核心点是文档写的对不对,专不专业。如果Code Review做的好的话,文档的Review也属于Code Review的一部分。
    • 读者视角保证简洁性: 一般由不熟悉这个领域的人来Review,比如团队的新人,或者文档的使用者。这部分主要是关注文档是否容易被看懂。
    • 写作者视角保证一致性: 由写作经验丰富或者相关领域比较资深的人承担,主要是为了保证文档前后是否一致,比如对同一个专业术语的使用和理解是否有歧义。

    写文档的哲学

    上面部分站在组织和团队的视角来看如何提高文档质量,我们接下来看看站在个人写作者的视角上如何写出高质量的文档。

    5W法则

    5W法则相信大家已经听的多了,分别是Who What When Where Why,这是一个广泛被用在各行各业的法则,写文档当然也能用(5W法则堪称万金油,啥地方都能用)。

    • WHO: 前面已经说过了,文档是写给谁看的,读者是谁。
    • WHAT: 明确这篇文档的用途,有时候,仅仅说明文档的用途和目的就能帮你搭建起整个文档的框架。
    • WHEN: 明确文档的创建、Review和更新日期。因为文档也有时效性,明确相关日期可以避免阅读者踩坑。
    • WHERE: 文档应该放在哪! 建议一个组织或者团队有统一的永久文档存放地址,并且有版本控制。最好是方便查找、使用和分享。
    • WHY: 为什么要写这篇文档, 你期望读者读完后从文档中获得什么!

    三段式写作

    写文章一般都会有三个部分,专业写作者也讲究凤头、猪肚、豹尾,这三个词概括出了好文章三部分应有的特点。技术文档也算是文章的一种,所以一般也都会有这三部分,每个部分有其自己的作用,比如第一部分阐述问题,中间部分介绍具体的解决方案,第三部分总结要点。 但这也并不以为着文档应该有三个部分,如果文档内容比较多,可以将其做更细致的拆解,可以适当增加一些冗余的信息帮助读者理解文档内容。虽然很多工程师都讨厌冗余 极力追求简洁,但写文档和写代码不同,适当的冗余反而可以帮助读者理解,很简单,举个例子,比如写作中经常举例子,举的例子本质上就是冗余信息,生动的例子肯定是能帮助读者理解抽象内容的(我想这就是自举
    吧)。

    结语

    目前看到比较好的一个现象就是大家越来越重视文档了,但和测试相比 重视的程度还不够。测试已经是工作流程中不可或缺的一部分了,而文档依旧还不是。当然这可能和文档本身的特性相关,测试很容易被自动化,也有非常多的客观指标来评估。文档却做不到,首先文档的书写需要人手动介入,而文档的质量也没有太多客观的指标评估,提升文档的数量和质量只能从文化和工作流程上去逐渐改变。

    最后总结下本文几个关键点:

    • 随着时间的推移和组织规模的壮大,文档会越来越重要。
    • 文档也应该是开发流程的一部分。
    • 一篇文档只专注在一件事上。
    • 文档是写给读者看的,而不是给你自己看的。
    展开全文
  • Guns技术文档.pdf(完整版),帮助开发人员快速上手该框架的开发。(Guns 技术文档 v1.0.pdf)
  • 技术文档模板——word模板

    热门讨论 2010-02-24 14:53:10
    自己整理的word模板,技术文档模板,可用于公司内部或外部交流。
  • Guns 完整技术文档

    热门讨论 2018-07-25 15:17:19
    Guns技术文档全套的哦,是真的完整版,很清晰完整版的文档
  • 优秀程序猿写技术文档的正确姿势

    万次阅读 多人点赞 2019-06-12 20:21:41
    一、背景 写文档是程序猿进阶的一个...最近有小伙伴问怎么写技术文档,结合了多个优秀的技术文档的范例,总结了技术文档的框架。 二、框架 话不多说,直接上干货。 2.1 技术文档的架构 关键是能够条理清...

    一、背景

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

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

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

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

    二、框架

    话不多说,直接上干货。

    2.1 技术文档的架构

     

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

     

    2.2 考虑的因素

    我们主要考虑:

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

    三、推荐图书和软件

    3.1 推荐图书

    《大象UML》、《UML精粹》

    3.2 推荐作图软件

    工欲善其事必先利其器。

    作UML图推荐Viso、ProcessOnPlantUml、UmlStar、OmniGraffle等。

    3.4 推荐思维导图工具

    mindnode、xmind、ithougthtX等

    四、思考

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

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

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

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

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

     

    五、相关参考

    优秀的程序员还可以考虑抢产品的饭碗,多学点总没错,可以看看这篇文章学学需求文档的写法:

    《优秀产品经理写需求文档的正确姿势》

    创作不易,如果觉得本文对你有帮助,欢迎点赞,欢迎关注我,如果有补充欢迎评论交流,我将努力创作更多更好的文章。

    另外欢迎加入我的知识星球,知识星球ID:15165241 一起交流学习。

    https://t.zsxq.com/Z3bAiea  申请时标注来自CSDN。

    展开全文
  • 如何编写高大上的技术文档 作为程序员,除了会写代码,能查bug,还要会画图(UML建模)、做PPT(分享、述职等),更重要的是还要能写得出文档,并且能写出高大上的文档。 根据过往的经验,技术文档一般会: ...

    如何编写高大上的技术文档

    作为程序员,除了会写代码,能查bug,还要会画图(UML建模)、做PPT(分享、述职等),更重要的是还要能写得出文档,并且能写出高大上的文档。

    程序员如何编写高大上且实用的技术文档

     

    根据过往的经验,技术文档一般会:

    项目文档:

    用于开启新项目的整体概要文档,说明项目背景、成员、依赖关系、项目整体排期、里程碑等信息。

    部署文档:

    介绍网站或系统如何进行部署,搭建运行环境,通常需要说明代码的Git仓库位置、数据库结构、Nginx/Apache配置、计划任务配置、其他配置,是否需要CDN或HTTPS等,以及注意事项。

    接口文档:

    针对每个API接口提供的文档,说明接口地址,调用方式,接口参数,返回结构,异常情况等。

    模板文档:

    提供给前端使用的模板文档,说明每个网站页面会存在哪些变量、类型是什么、以及处理逻辑,方便前端进行渲染、展示和交互。

    设计文档:

    针对系统、子系统或某个功能模块的设计说明,从技术架构到软件设计,到数据库建模,以及核心技术的介绍,性能分析等,面向对象是相同专业的专业人员。

    开发文档:

    针对每个开发需求而编写的文档,说明需求的背景、当前需求的实现思路,并记录这个需求所产生的接口文档、模板文档、数据库变更、上线待办清单、代码仓库和相应的开发分支,以及一些注意事项,方便需求在开发过程中,以及在测试联调过程中,有很好的文档进行备忘、沟通和回顾。如果有依赖底层或第三方的接口,也应一并补充。若有外部调用方,也应进行登记。

    故障文档:

    当出现线上故障时,处理完毕后,应编写故障复盘文档,进行原因分析、思考改进措施、贴出关键的代码、交待故障发生以及处理的历史过程,方便团队进行回顾、学习和避免类似问题再次发生。

    分享文档:

    对新技术或已有技术的技术分享,例如:如何利用docker部署本地开发环境。

    新人文档:

    为新加入团队成员而编写的新人指引教程,包括系统介绍、应该开通哪些账号、遇到的一些常见问题、入周第一周应该做什么等。

     

    除此之外,还有系统负责人文档、数据库文档、版本文档、需求文档等,不一一列出。

    文档编写的要点

    切记,编写文档的目的是为了让读者可以快速有效地获取他想知道的信息。

     

    因此,文档编写规则第一条:要简单、清晰、明了。不要为了凑字数而堆字数。

     

    文档编写第二条:明确文档面向的读者和受众。根据所编写的文档,判断主要面向的受众是产品、技术、测试还是商务人员,尽量使用他们所能理解和熟悉的词汇和表达方式来表达。

     

    文档编写第三条:提供必要的信息。根据需要编写的技术类型,提供必要的信息,就像摄影拍照一样,有一些约定的摄影构图,例如:均衡式构图、对称式构图、对角线构图、三角形构图、九宫格构图等。文档也是一样,不同文档需要包含的元素、标题和部分也有所不同。然后当你熟悉 后,可灵活安排文档的内容,以最为恰当的结构形式来表达。

     

    文档编写第四条:排版与图片。尽量不要一味地只提供文字信息,这样会让读者看起来很压抑而且觉得是“天书”。应该适当留一些空行,让读者眼睛“休息”下,对读者友好一些。同时,提供一些代码片段、UML图片或相关的插图用于辅助说明。补充一些参考的文献和资料。排版上,进行分段,分章节部分,注意对重要的信息高亮、加粗、或重复说明。

     

    文档编写第五条:万事开头难。很多技术人员觉得编写文档比写代码还要难,还要头疼。其实写文档和写代码是类似的,很难一开始就写出完美的文档。应该是像写代码一样,一开始写得很丑陋,但没关系,至少有内容了。然后,可以不断重构文档,对缺少的信息补全,对多余的信息进行删除。最后觉得内容上OK的话,就可以再进行排版和修饰,补充一些图片。慢慢的,在通过用心花时间后,你的完美文档就慢慢出来了。

     

    使用主流的markdown格式进行文档编写

    首先,向小白程序员介绍一下markdown这种格式。这是一种很主流的格式,Markdown是一种可以使用普通文本编辑器编写的标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式。说白了,就是它可以再转换成HTML代码,最后进行文档排版。

    现在,已经有很多平台都支持了markdown的格式。

    例如,Gitlab、Github、Gee:

    程序员如何编写高大上且实用的技术文档

     

    又如各大信息类平台:

    图灵社区:

    程序员如何编写高大上且实用的技术文档

     

    掘金:

    程序员如何编写高大上且实用的技术文档

     

     

    另一方面,支持markdown的语言、系统、IDE开发环境、软件、平台和js编辑器也很丰富。

    程序员如何编写高大上且实用的技术文档

     

     

    markdown格式也是很容易理解的,例如大标题、小标题的格式:

    # 一级标题
    ## 二级标题
    ### 三级标题
    #### 四级标题
    ##### 五级标题
    ###### 六级标题 

    其他格式可自行查阅各大资料说明。

     

    使用本地文本编辑器编写markdown文档

    不管你用的是windows系统,还是Linux,还是Mac手提,都有很多文本编辑器是支持markdown的编写以及预览。

     

    markdown文档的后缀名是md,例如常见的顶顶有名的README.md。

    程序员如何编写高大上且实用的技术文档

     

    例如我在Macbook上使用SubEthaEdit:

    程序员如何编写高大上且实用的技术文档

     

    编辑界面如下(后面可以看到相应的访问效果):

    程序员如何编写高大上且实用的技术文档

     

    在编辑时,编辑器会自动帮你进行markdown格式的高亮,非常友好。

     

    SubEthaEdit官方的介绍。

    程序员如何编写高大上且实用的技术文档

     

    使用docsify搭建你的文档网站

    了解完伟大的markdown格式后,接下来你就可以使用docsify把写好的markdown文档进行在线展示了。

    docsify是一个基于javascript运行的开源项目,不需要任何PHP、java、数据库后端的依赖,就可以直接展示你的在线文档。

     

    docsfiy官网:https://docsify.js.org/#/?id=docsify-4113

    显示效果:

    程序员如何编写高大上且实用的技术文档

     

    来一个更完整的文档截图:

    程序员如何编写高大上且实用的技术文档

     

    不用担心英文的问题,文档上的内容都是可以自己设置和编写的。

     

    docsify支持文档搜索、左侧菜单、顶端菜单、封面等。

     

    例如,PhalApi开源框架使用docsify搭建的效果:

    项目封面:

    程序员如何编写高大上且实用的技术文档

     

    文档正文:

    程序员如何编写高大上且实用的技术文档

     

    搜索效果(留意左边):

    程序员如何编写高大上且实用的技术文档

     

     

    同时完美支持移动端访问文档:

    程序员如何编写高大上且实用的技术文档

     

    用果创云文档编写你的技术文档

    最后,如何你不想搭建自己的文档网站,也可以直接使用果创云的在线文档,来编写自己的技术文档,分享你需要分享的项目成员查看。

     

    果创云在线文档就是基于docsify搭建和markdown格式来编写的。

     

    首先,进入果创云开放平台:http://open.yesapi.cn

     

    然后,进入【文档】:http://open.yesapi.cn/wiki/home

    程序员如何编写高大上且实用的技术文档

     

     

    进入后,便可以创建你的项目文档,支持创建多个项目文档。

    程序员如何编写高大上且实用的技术文档

     

    接着,就可以在线编辑你的文档,并且实时预览。

    程序员如何编写高大上且实用的技术文档

     

     

    编写完成后,就可以查看你的文档。

    程序员如何编写高大上且实用的技术文档

     

    文档展示效果:

    程序员如何编写高大上且实用的技术文档

     

     

    为保护你的文档,你可以设置项目文档的查看密码:

    程序员如何编写高大上且实用的技术文档

     

    这时候,需要填写密码才能查看你的文档:

    程序员如何编写高大上且实用的技术文档

     

     

    展开全文
  • 程序员如何写技术文档

    千次阅读 2020-08-23 17:26:46
    1.什么是技术文档 在工作中或者在发布开源项目时,需要编写技术文档,以便别人使用时,或者自己过了很久之后去看不会一脸懵逼。 我觉得写技术文档应该是一个程序员必备的技能,好的技术文档包括以下几个特性: 结构...
  • java web开发技术文档的编写

    千次阅读 2020-04-17 17:18:52
    技术文档分类: 分为开发(研发)文档和客户文档 开发文档: 项目开发过程中为了增加程序的可读性和程序的健壮性, 方便后期程序的调试和维护,所以需要在开发过程中统一技术规范,一般会在项目初期确定好相关文档...
  • 技术文档编写经验总结

    千次阅读 2019-04-18 23:25:36
    又一个项目即将结束,从编写技术文档、代码开发到联调,8个人还不到两周的时间,居然完成了,想想自己都很吃惊。 虽然是个小项目,但还是有很多东西需要沉淀下来。 正好晚上吃饱了没事干,写个博客记录一下技术...
  • 技术文档写作的职业探讨

    千次阅读 2017-09-21 15:17:39
    转自 http://blog.csdn.net/u014309159/article/details/44904425 原文链接:...  外面的人通常不知道技术文档写作这个职业是做什么的. 这个职业究竟参与了哪些工作? 这个行业是什么样子
  • 如何看英文技术文档

    千次阅读 2018-12-06 11:49:33
    本文以jekyll官方文档为例。 为小白简单介绍一下,jeyll就是一个静态博客生成器,你只要按照它给定的规则进行相关的配置后,你就可以只要专心写文章,什么数据库管理、自己搭建一个CMS系统等麻烦事情都不要管,也...
  • python技术文档的阅读理解

    千次阅读 2021-12-15 16:22:24
    1、我想阅读python官网的技术文档,于是打开了官网地址 (1)中文地址:8. 复合语句 — Python 3.10.1 文档...
  • 技术文档系列之架构设计文档模板

    千次阅读 2019-09-12 22:57:52
    本文是对专栏文章架构设计文档模板的学习记录,可以购买以支持原作者 首先是备选方案模板 需求介绍 主要介绍需求的背景,目标与范围 随着xxx业务不断发展,业务拆分的子系统越来越多(阐述现有系统的问题),由此带来...
  • 技术文档的作用

    千次阅读 2016-08-29 21:17:27
    在做项目的过程中,发现居然有人不知道技术文档的作用,以及如何写技术文档,可能因为所处环境的特殊,大家对基本的计算机知识都不是很懂吧!我查了一些资料,根据自己的理解,谈一谈技术文档吧! 2. 概念 技术文档...
  • 你很希望别人能写技术文档,而自己却很不希望要写文档。即使有文档,也是零零散散地放在团队不同人手里,到硬盘里搜一波,用 QQ 、邮箱直接丢,这种沟通当然可以,只是效率不高。 ShowDoc 是款适合 IT 团队的在线...
  • JAVA设计模式学习【技术文档

    千次下载 热门讨论 2014-01-08 14:50:55
    JAVA设计模式的一个基础介绍,适合对java学习感兴趣的人士参考,129页,doc格式。
  • Java web 项目技术文档目录结构

    千次阅读 2018-11-26 11:00:23
    近期项目比较忙,没有更新文章,现在到了项目收尾阶段,正好在准备技术文档,所以把这个技术文档的目录和大家共享一下。 下面目录是我在参考了几个项目文档后自己总结出来的,每个章节之间不是递进关系(如四是对三...
  • Java相关技术文档汇总

    千次阅读 2018-03-09 11:06:28
    Java弱引用(WeakReference)的理解与使用 Java读取、写入、处理Excel文件中的数据 javaSwing教程 Java GUI swing 可执行程序 jar (java -jar)idea IDEA Swing UI Designer form无法直接运行 ...
  • 本文主要讲解的是用vuepress搭建一个技术文档,且这个技术文档是与github pages 相关联的。就是我们常见的下图的这种:   最终效果如下图:   如果与你想要做的一样,请仔细阅读下面的内容。 重要提示 ...
  • 软件开发技术文档编写规范

    万次阅读 多人点赞 2017-12-29 09:40:14
    在项目开发过程中,应该按要求编写好十三种文档文档编制要求具有针对性、精确性、清晰性、完整性、灵活性、可追溯性。  ◇可行性分析报告:说明该软件开发项目的实现在技术上、经济上和社会因素上的可行性,评述...
  • 苹果MFI技术文档

    热门讨论 2015-03-20 09:46:45
    苹果接口开发的技术文档,MFi Accessory Hardware Specification R8,Accessory Interface Specification R1等。
  • 本文的记录与总结依照于FISCO BCOS 技术文档学习联盟链搭建的相关知识,详细搭建过程见文档,本文仅作参考 本文通过在单机上部署一条4节点的FISCO BCOS联盟链,掌握FISCO BCOS部署流程。 搭建 需要使用已经封装...
  • 普元产品技术文档库(官方)

    千次阅读 2017-04-18 09:32:11
    推荐使用普元产品技术文档库(http://doc.primeton.com),该文档库 1:无需登录 2:全部售后已解决问题的解决方案和知识点,基本上客户90%以上的问题都能搜到答案 3:产品所有补丁公示 4:产品培训视频 5:SOA产品...
  • HTML5开发APP技术文档

    千次阅读 2018-03-05 17:36:22
    HTML5开发APP技术文档   一、环境参数 1、技术语言:HTML、CSS、ES6、Node.js等; 2、框架:Vue.js 2.x、Cordova; 3、开发系统:mac、windows等; 4、环境配置: node 6+ npm 3+ (最好下载Node.js官方...
  • Unity 3D中文开发技术文档

    千次阅读 2015-03-03 17:12:18
     http://uec.unity3d.com/learning
  • web前端开发技术文档书写规范

    千次阅读 2016-07-20 11:18:08
    本文为转载:详情见 http://blog.csdn.net/zk437092645/article/details/8641454
  • 2.实现回调接口根据本文档实现对应的回调接口,此回调接口会在用户使用金山文档服务的时候被调用,金山文档通过对应的回调接口获取对应的文件信息,这些接口都是被金山文档服务端调用,不会直接暴露给用户。...
  • 初识DocBook(编写技术文档的工具)

    千次阅读 2014-05-29 14:22:54
    突然在Linux下看到一堆命令: [root@localhost default]# do do docbook2rtf docbook2txt dosfsck doveconf doxytag ...基于此,Developer可以编写,修改和管理技术文档,并实现“一次编写,随便阅读”。

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 1,265,107
精华内容 506,042
关键字:

技术文档

友情链接: spgl1-1.9.zip