精华内容
下载资源
问答
  • 如何编写技术文档

    2015-02-09 17:20:00
    最近在公司内部审查,我想不是我们中国软件行业的个别问题,相反,存在一定的普遍性。以下我列出了几个值得提高的地方。 1) 文档的格式上存在...好的文档应当是从头到尾保持格式的一致性,这不仅仅是一种美,更是...

    最近在公司内部审查,我想不是我们中国软件行业的个别问题,相反,存在一定的普遍性。以下我列出了几个值得提高的地方。

    1) 文档的格式上存在不一致性的问题。格式有时是这样,有时是那样。一篇好的文档我想不光是内容写得好,其格式是很重要的一部分。试想,如果我们拿到了一篇格 式上写得乱七八糟的文档,这一第一印象会影响我们的阅读心情吗?好的文档应当是从头到尾保持格式的一致性,这不仅仅是一种美,更是专业性的一种表现。

    2) 写文档的作者不能很好的站在读者的角度去思考。要写出一篇好的支持文档,作者应当站在读者的角度上去写。这简单的一句话,要操作起来,将其做好,还真不是 一件容易的事。在写文档时,如果不站在读者的角度去思考,很容易写出一篇“自己一看觉得清清楚楚,别人一看却糊里糊涂”的文档。

    3) 文档求长不求精。一说到写文档,我不知是否有人将“文档应当长”当作是文档的必要属性。对于这一点,我想正确的态度是:求精不求长。一篇好的文档,应当写 得简练易懂。写文档的目的是什么?是为了让别人明白我们所要说明的问题,要说明问题,并不需要一定将其写得长。一篇精炼的文档也意味着效率,即读者花很少 的时间就明白我们想要表达的问题是什么。当然,从作者的角度来看,要写一篇精炼的文档,那得花更多的时间去斟酌。

    4)图太少。有图不是一篇好文档的必要条件,但在不少情况下,用一幅图能很好的表达我们的思想,不是有那么一句话吗“好图胜过千言万语”,适当的采用一些图,一方面能为文档增色,另一方面也能更好的向读者传达我们的意图。

     

    好了,值得提高的点也提出来了,如何去做好呢?我想下面是我所能想到的一些方法,在此,将与上面的提高点一一对应进行阐述。

    1)对于格式问题,找一篇自己觉得格式不错的文档进行模仿,并将其做成一个模板,每次写作时以这一模板为基础。

    2) 写完以后,假设自己是读者多次阅读自己的文档。这一点要做好还是很难的,因为,我们很难完全站在读者的角度去读自己写的文档,我们不知道自己所知的哪些东 西是读者所不知的,即很难界定与读者知识不对称的分界点。为了提高这一点,我想我们写文档时,应当多问自己一些问题,比如,读者具有与我一样的知识和经验 吗?如果没有,我应当写哪些以弥补这种信息的不对称性呢?我写的这篇文档是基于一定的假设吗?如果是,是否应当将这一假设在文档中交代清楚呢?我所写的内 容是否都在支持文档的主题呢?是否存在正交问题(即答非所问的问题)?等等。

    3)在文档写完后多问一问自己,这篇文档还能写得更简单吗?是否可以将一些文字省去并用一幅图取而代之以达到使其简练的目的呢?不防时刻对自己说,简单也是一种美!

    4) 学习(并精通)一些行业所需的图形语言和工具,并加以运用。比如,我们软件行业的UML就是很好的一种表达语言,且随着UML的发展,其表达能力更加的强 大。目前,业内有很我UML的工具,找一个不错的就行了,比如Visual Paradigm的UML工具就不错,工具其实只是一种工具,关键是掌握UML。只有我们很好的掌握一种图形语言,我们才有可能随时加以运用,从而为我们 的技术文档服务。当然,像Microsoft的Viso也是不错的绘图工具,这要看我们想表达的是什么,从而加以灵活运用各种工具。

     

    至 此就好了吗?不,还有很重要的一点是:我们需要在思想上做一些改变,这种改变是什么呢?那就是:写出一篇好的技术文档是一个专业软件工程师的必要素养!我 们必须抛弃那种软件工程师只要能写出漂亮的代码就行了的思想,而是要将“写好每一篇技术文档是专业软件工程师的必要素养”这一句话深入到我们的骨髓当中 去,只有这样,我们所写的技术文档才会越来越好、才会越来越专业。

    转载于:https://www.cnblogs.com/newzhq/p/4282011.html

    展开全文
  • 重点 (Top highlight) 如何编写好的软件技术文档 (How to write good software technical documentation)This article aims to help developers to write better documentation. As a developer, I hate writing ...

    软件技术文档编写

    重点 (Top highlight)

    This article aims to help developers to write better documentation. As a developer, I hate writing documentation. But I hate even more reading undocumented code. I describe here what I expect from a good documentation and why it is necessary.

    本文旨在帮助开发人员编写更好的文档。 作为开发人员,我讨厌编写文档。 但是我讨厌更多地阅读未公开的代码。 我在这里描述了我对良好文档的期望以及为什么有必要。

    First of all, you need to understand you are not writing documentation for you, nor for your current team. You are writing documentation for the future developers that were not there when you first wrote this code. Worst of it, they might think it is bad code for many reasons and won’t understand why you wrote this way.

    首先,您需要了解您不是在为您自己,也不为您当前的团队编写文档。 您正在为首次编写此代码时不存在的未来开发人员编写文档。 最糟糕的是,由于许多原因,他们可能会认为它是错误的代码,并且不明白您为什么以此方式编写。

    Image for post
    CommitStrip.com)CommitStrip.com )

    代码文件 (Code documentation)

    I often hear that a good code does not need documentation. I totally agree with this statement. I am not here to explain how to write good code but good documentation. If you want to know how to write good code, you can start by reading this : https://medium.com/@isaaclyman/steps-to-better-code-e6c3cce0c7f9.

    我经常听到,好的代码不需要文档。 我完全同意这一说法。 我不是在这里解释如何编写好的代码,而是好的文档。 如果您想知道如何编写好的代码,可以先阅读以下内容: https : //medium.com/@isaaclyman/steps-to-better-code-e6c3cce0c7f9

    Naming should represent 99% of the documentation of your code. No need to add unnecessary comments to explain what you’re trying to do. It’s like as a French translator, you write some English comments in your translation for the next person that will update your work. We can easily guess that the next translator speaks both French and English, so he doesn’t need the text in both languages. It is the same with a developer: he can understand both code and natural language. So you don’t need to write English translation of your software code.

    命名应占代码文档的99%。 无需添加不必要的注释来解释您要执行的操作。 就像是法语翻译一样,您在译文中写了一些英语注释,以供下一个人更新您的作品。 我们很容易猜到下一位翻译会说法语和英语,因此他不需要两种语言的文字。 开发人员也是如此:他可以理解代码和自然语言。 因此,您无需编写软件代码的英文翻译。

    Here is an example of unnecessary comments :

    这是一个不必要的注释示例:

    # Example of unnecessary comments// This function will process orders items attributes
    function processOrdersItemsAttributes(orders: Array) {
    // I iterate the orders
    foreach (orders as order) {
    // I iterate the orders items
    foreach (order->getOrderItems() as items) {
    // I iterate the items attributes
    foreach (items->getItemAttributes() as attribute) {
    // I process the attribute
    process(attribute)
    }
    }
    }
    }

    函数和方法标题注释 (Functions & Methods header comments)

    Today, IDEs can automatically generate function and method headers comments (see example below). These comments can be transformed into code documentations (often in HTML or PDF).

    今天,IDE可以自动生成函数和方法标题注释(请参见下面的示例)。 这些注释可以转换为代码文档(通常为HTML或PDF)。

    It’s sometimes useful to improve them by adding more information about the behaviour of your function, the incoming parameters or the outgoing results. But as I said previously, naming (and types) should be enough to understand what a function does, especially if the function has only one purpose.

    有时通过添加有关函数的行为,传入参数或传出结果的更多信息来改善它们是有用的。 但是正如我之前说的,命名(和类型)应该足以理解一个函数的功能,尤其是在该函数仅具有一个用途的情况下。

    Image for post
    Auto-generated header comments
    自动生成的标题注释

    So what should appear in the technical documentation if there is no need to comment the code ?

    那么,如果不需要注释代码,在技术文档中应该显示什么呢?

    产品文件 (Product documentation)

    The product documentation is definitely something you should write and maintain. It should not be ‘technical’ (I mean it should be understandable by people who are not developers).

    产品文档绝对是您应该编写和维护的内容。 它不应该是“技术性的”(我的意思是它应该是非开发人员可以理解的)。

    It contains the list of all the features provided by your software and how they work. Whenever you develop something new, you should immediately update the documentation with the new behaviour you are implementing. It can also be used as the User Documentation, to help software users understand how to use it.

    它包含软件提供的所有功能以及它们如何工作的列表。 每当您开发新内容时,都应立即使用要实现的新行为来更新文档。 它也可以用作用户文档,以帮助软件用户了解如何使用它。

    技术架构 (Technical schemas)

    Here we start talking about something meaningful: schemas. A schema is a visual representation of a complex engineering solution. It should be understandable without any other text, but I recommend writing a small paragraph to explain how to read it to make sure everyone understands the same thing.

    在这里,我们开始讨论一些有意义的东西:模式。 模式是复杂工程解决方案的直观表示。 无需任何其他文本,它应该是可以理解的,但是我建议写一个小段来解释如何阅读它,以确保每个人都理解同一件事。

    There are a lot of them that can be useful. I give you a non-exhaustive list of them:

    其中有很多可能有用。 我为您提供了一个不详尽的清单:

    • Database Schemas: this is very useful for quickly understanding the relation between many entities of your software. Notice here that you can map only a few entities (not the whole model) in a schema to make it even easier to read.

      数据库模式:这对于快速了解软件的许多实体之间的关系非常有用。 请注意,您只能在模式中映射少数几个实体(而不是整个模型),以使其更易于阅读。
    Image for post
    Example of database schema
    数据库架构示例
    • Software Architecture Schemas: which explains how different parts of your software interact together. It can represent logical or physical. For example, it can detail how one specific micro-service is designed (logical), or how your code is deployed in the cloud (physical).

      软件体系结构架构:解释了软件的不同部分如何相互作用。 它可以表示逻辑或物理。 例如,它可以详细说明如何设计一种特定的微服务(逻辑),或如何在云中部署您的代码(物理)。
    Image for post
    Image for post
    Left: example of logical architecture ; Right: example of physical architecture
    左:逻辑体系结构示例; 右:物理架构示例
    • Sequence Diagram: it displays the successive stages of a complex flow

      顺序图:显示复杂流程的连续阶段
    Image for post
    Example of sequence diagram
    时序图示例

    Every software technical documentation should at least have a model schema, a global logical architecture schema and a global physical architecture schema to help understand how it is engineered and how to build over the existing source code.

    每个软件技术文档至少应具有一个模型架构,一个全局逻辑体系结构架构和一个全局物​​理体系结构架构,以帮助了解其设计方式以及如何在现有源代码之上构建。

    技术决策日志 (Technical decision logs)

    This is the most important thing to add into a technical documentation, and by experience, the least written. The objective is simple: explain how and why we chose each solution. You only need to write a short sentence to explain the context and the constraints you encountered in making this decision and why you think it is the best (in this context). You can also add some food for thought if some constraints are removed.

    这是添加到技术文档中最重要的事情,而从经验上讲,最不容易编写。 目标很简单:说明我们如何以及为什么选择每种解决方案。 您只需要写一个简短的句子来说明上下文以及在做出此决策时遇到的限制以及为什么您认为最好(在此上下文中)。 如果消除了一些限制,您还可以考虑一些问题。

    For example, if you have to deliver a new functionality within only one week to validate a market fit, you will try to take a shortcut and write ‘dirty’ code. If you explain this in the log, when another developer reads this code and this log, he will understand that he should now rewrite the shortcut instead of patching the ‘dirty’ previous work.

    例如,如果您必须在一周内交付新功能以验证市场契合度,则您将尝试采取捷径并编写“肮脏”代码。 如果您在日志中对此进行了解释,那么当另一个开发人员阅读此代码和该日志时,他将理解他现在应该重写快捷方式,而不是修补先前的“肮脏”工作。

    The code doesn’t last forever. It is often improved, replaced or deleted. If you explain the context of a piece of code, the next developer will be able to understand it and make the right decision with the new context. I recommend having a wiki or a markdown file in your repository to write all these logs. It can be linked to the product documentation if this one is versioned.

    该代码不会永远持续下去。 它经常被改进,替换或删除。 如果您解释了一段代码的上下文,那么下一个开发人员将能够理解它,并根据新的上下文做出正确的决定。 我建议您在存储库中有一个Wiki或Markdown文件来写入所有这些日志。 如果对此进行了版本控制,则可以将其链接到产品文档。

    Let’s go back to our previous code for a second example:

    让我们回到前面的代码中获得第二个示例:

    function processOrdersItemsAttributes(orders: Array) {
    foreach (orders as order) {
    foreach (order->getOrderItems() as items) {
    foreach (items->getItemAttributes() as attribute) {
    process(attribute)
    }
    }
    }
    }

    Without any information, I can say this is very bad code because there are 3 nested loops and the complexity of this function is far too high. Maybe we should use asynchronous mechanisms to process attributes faster.

    没有任何信息,我可以说这是非常糟糕的代码,因为有3个嵌套循环,并且此函数的复杂性太高了。 也许我们应该使用异步机制更快地处理属性。

    Now I give you some context:

    现在我给你一些背景:

    Orders length, orders items length and attributes length are expected to be close to 1 so we decided to process then sequentially.

    订单长度,订单商品长度和属性长度预计接近1,因此我们决定按顺序进行处理。

    Do you still want to use asynchronous to process a few attributes ? I don’t think so.

    您是否仍要使用异步处理一些属性? 我不这么认为。

    I give you more context:

    我给你更多的背景:

    The process of each order item attribute depends on the previous one it the same order item.

    每个订单项属性的处理取决于同一订单项的前一个属性。

    Now we need to process thousands of orders, order items and attributes. With the context & decision log, you can rewrite the code taking in consideration these constraints. Without the context in the decision log, you risk breaking the previous code.

    现在,我们需要处理数千个订单,订单项和属性。 使用上下文和决策日志,您可以考虑这些约束来重写代码。 如果决策日志中没有上下文,则可能会破坏先前的代码。

    A piece of software without documentation is worthless. The documentation should reflect the engineering part, not the code itself. By reading the documentation, you should understand how previous developers build the product and be able to delete all the source code and recreate everything from scratch. If you can do so, it is good software technical documentation.

    没有文档的软件毫无价值。 文档应反映工程部分,而不是代码本身。 通过阅读文档,您应该了解以前的开发人员如何构建产品,并能够删除所有源代码并从头开始重新创建所有内容。 如果可以的话,它是好的软件技术文档。

    翻译自: https://medium.com/@VincentOliveira/how-to-write-good-software-technical-documentation-41880a0e7814

    软件技术文档编写

    展开全文
  • 文档版本清晰化,充分利用Git 的版本管理能力,轻松对比不同版的修改演进。 减少在文档格式排版上的投入,争取简历上不再有精通word。 充分利用开发者既有工具,减少工具量,少就是多。 工具链 OS:macOS Mojave V...

    需求

    1. 文档版本清晰化,充分利用Git 的版本管理能力,轻松对比不同版的修改演进。
    2. 减少在文档格式排版上的投入,争取简历上不再有精通word。
    3. 充分利用开发者既有工具,减少工具量,少就是多。

    工具链

    • OS:macOS Mojave V10.14.3
    • IDE:Visual Studio Code
    • Visual Studio Code扩展插件:

      • markdownlint:在写书中如有违规,会在编辑区提示你。
      • Markdown PDF:将 md 文件转换为 pdf、html、jgp 等,便于非技术人员阅读。
      • Preview:预览最终效果。
      • Excel to Markdown table: 将 Excel 表快速变成 markdown 格式的。

    技术文档基本元素的实现

    文章标题及各章节标题

    用“#”来标记标题,每增加一级增加一个 # ,字号也会减小。# 和文字之间留一个空格。

    # 史上最牛的设计方案
    ## 1. 产品需求
    ### 1.1 功能需求
    #### 1.1.1 移动端需求
    ##### 1.1.1.1 iOS 版需求
    ###### 1.1.1.1.1 支持 Carplay
    ### 1.2 非功能需求
    ## 2. 产品设计
    ## 3. 资源需求

    信息列表

    在文字前面加上 * 或 数字 1. 2. 3. 等即可显示列表。

    无序列表的语法示例

    * 性能需求
    * 稳定性需求
    * 兼容性需求
    无序列表的显示效果
    • 性能需求
    • 稳定性需求
    • 兼容性需求

    有序列表的语法示例

    1. 设计约束1
    2. 设计约束2
    3. 设计约束3
    有序列表的显示效果
    1. 设计约束1
    2. 设计约束2
    3. 设计约束3

    表格

    语法示意

    | 序号 | 姓名 | 年龄  |
    |---- |:----:| ----:|
    |  1  | 张三 | 20 |
    |  2  | 李四 | 30 |
    |  3  | 王五 | 40 |

    显示效果:

    序号 姓名 年龄
    1 张三 20
    2 李四 30
    3 王五 40

    说明:

    • ”:---:“ 居中对齐
    • ”---:“ 右对齐
    • 默认左对齐

    基于插件快速搞定

    手工编辑大表有点反人性,基于“Excel to Markdown table”会省心很多,具体如下:

    1. 在 Excel 中建好所用表
    2. 回到VS Code 中,打开需要粘贴的 md 文件
    3. 使用快捷键“Shift + Alt + V”
    4. 完成。

    嵌入代码

    • 需要引用代码时,如果只引用一段,不用分行,可以用 ` 将语句包起来。
    • 如果引用的语句为多行,可以将```置于这段代码的首行和末行,在开始的```后面加上语言,便于相关解析器排版配色。

    示例1: bash语句

    示例1:语法

    ```bash

    #!/bin/bash

    echo Hello world

    ```

    示例1:最终效果
    #!/bin/bash
    echo Hello world

    示例2: sql语句

    示例2:语法

    ```sql

    SELECT Persons.LastName, Persons.FirstName, Orders.OrderNo
    FROM Persons
    INNER JOIN Orders
    ON Persons.Id_P = Orders.Id_P
    ORDER BY Persons.LastName

    ```

    示例2:最终效果
    SELECT Persons.LastName, Persons.FirstName, Orders.OrderNo
    FROM Persons
    INNER JOIN Orders
    ON Persons.Id_P = Orders.Id_P
    ORDER BY Persons.LastName

    链接

    语法

    [a link](https://commonmark.org/)

    最终效果

    a link

    图片

    与链接类似,使用 [图片说明](图片地址)]] 来展示图片。

    • 网络图片

      • ![网络图片](http://upload-images.jianshu.io/upload_images/2196493-4db4dd9ab5b27727.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)
      • 网络图片
    • 本地图片

      • [本地图片](本地图片地址)
      • 本地图片

    引用

    在需要引用他人的参考信息时,在引用的文字前面加上 > ,例如:

    > TPC Benchmark E is an on-line transaction processing (OLTP) benchmark. TPC-E is more complex than previous OLTP benchmarks such as TPC-C because of its diverse transaction types, more complex database and overall execution structure. 

    注:> 和文本之间要保留一个字符的空格。

    最终显示效果:

    TPC Benchmark E is an on-line transaction processing (OLTP) benchmark. TPC-E is more complex than previous OLTP benchmarks such as TPC-C because of its diverse transaction types, more complex database and overall execution structure.

    生成外发文档

    • 按 F1
    • 按提示选择 “markdown-pdf: Export (pdf)”
    • 按回车,即生成 PDF 文件

    常用Tips

    获得目录的树形展示

    Mac默认没有 tree 命令,又不想安装其他工具,可以通过下面的命令来救急。

    find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'

    预览效果

    • 方式1:使用侧边预览

      • 优点:markdown 编辑窗口与预览窗口并列,及时反馈。
      • 不足:空间受限,会影响排版效果。
      • 点击编辑框右上角图标启动。
    • 方式2:使用独立页面预览

      • 优点:完整展示效果
      • 不足:反馈滞后
      • 快捷键:Shift + Cmd + V

    扩展阅读

    展开全文
  • 编写技术文档,是令众多开发者望而生畏的任务之一。它本身是一件费时费力才能做好的工作。可是大多数时候,人们却总是想抄抄捷径,这样做的结果往往非常令人遗憾的,因为优质的技术文档是决定你的项目是否引人关注的...

    编写技术文档,是令众多开发者望而生畏的任务之一。它本身是一件费时费力才能做好的工作。可是大多数时候,人们却总是想抄抄捷径,这样做的结果往往非常令人遗憾的,因为优质的技术文档是决定你的项目是否引人关注的重要因素。无论开源产品或面向开发者的产品,均是如此。

    实际上,我想说明的是:对于面向开发者的产品来说,其用户体验中最重要的一环并不是什么主页设计、登录过程、或者SDK下载。真正最重要的是产品的API文档!如果没人知道你的产品如何使用,纵使它巧夺天工,又有何用?

    如果你是一个专门从事面向开发者产品设计的工程师,那么编写完善的技术文档,就跟你为终端用户提供良好用户体验一样关键。

    我见过许多类似的情况,一个项目被草率地扔到GitHub的页面上,仅仅配有两行的readme说明文件。要知道,真正成功的API文档是需要用爱来悉心制作的艺术品。在Parse产品项目里,我们就把自己奉献给了这门艺术!

    那么,什么才是制作优秀API文档的关键因素呢?

    1. 绝不吝惜使用层次

    你的设计文档不应当仅仅直白地列出所有的终端函数和其参数。好的文档应该是一整套有机的系统内容,能指引用户通过文档与API进行交互。退一万步说,你至少让你的文档包含以下几个部分。

    参考索引:参考索引应当是一个事无巨细的列表,包含了所有功能函数的繁文缛节。它必须注明所有的数据类型和函数规格。高级开发者要能够拿着它整天当参考书使用。

    开发指南:这是介于参考索引和开发教程中间程度的文档。它就仿佛是一篇更加详细的参考索引,阐明了如何使用各种API。

    开发教程:开发教程会更加具体地阐述如何使用API,并着重介绍其中的一部分功能。如果能提供可编译运行的源代码,那就再好不过了。

    在Parse项目里,我们做到了上述所有三个部分。目前我们正在努力编制更多的开发教程。

    另外一个此方面优秀的范例是Stripe’s API(http://www.stripe.com) 。这个产品的文档包括一个很棒的《hybrid guide and reference》,以及一套开发教程。《GitHub API参考》也经过了良好的设计。

    2. 不要在例子中包含抽象概念

    你可以争辩说,我的API本身就是个抽象体, 抽象就是它的特点。然而,当你在教会开发者如何使用的过程中,还是能不抽象就不抽象比较好。

    在你的文档中尽可能地举现实中的例子吧。没有哪个开发者会抱怨你举例太多的。实际上,这种做法能显著地缩短开发者理解你产品的时间。对此,我们的网站里甚至给出一个代码样例加以解释。

     

    如何编写优质的API文档

     

    3. 减少点击次数

    开发者痛恨点击鼠标,这已经不是什么秘密了。千万别把你的文档分散在数以万计的页面当中。尽量把相关的主题都放到一个页面里。

    我们非常赞成使用“单页面大指南”的组织形式(链接),这种形式不仅能让用户纵览全局,仅仅通过一个导航栏就能进入他们感兴趣的任意主题,另外还有一个好处是:用户在进行搜索的时候,仅仅搜索当前页面,就能涵盖查找所有的内容。

    在这个方面的一个优秀范例是ckbone.js documentation,只要你有个鼠标,一切尽在掌握。

    4. 包含适当的快速指南

    万事开头难,开发者学习一套全新的API,不得不重新适应其全新的思维方式,学习代价高昂。对于这个问题的解决办法是:通过快速指南来引导开发者。

    快速指南的目的是让用户用最小的代价学习如何利用你提供的API干一些小事。仅此而已。一旦用户完成了快速指南,他们就对自己有了信心,并能向更加深入的主题迈进。

    举个例子,我们的快速指南能让用户下载SDK以及在平台上存储一个对象。为此,我们甚至做了一个按钮,来让用户测试他们是否正确地完成了快速指南。这能提升用户的信心,以鼓励他们学习我们产品其他的部分。

    5. 支持多种编程语言

    我们生活在一个多语言的世界。如果可能的话,为你的API提供各种编程语言版本的样例程序,只要的API支持这些语言。多数时候,多语言的工作都是由客户端库来完成的。要知道,开发者要想掌握一套API,离开他们熟悉的编程语言,是很难想象的。

    MailGun’s API为此做出了良好的榜样。它提供了curl,Ruby,Python,Java,C#和PHP等多个版本供开发者选择。

    6. 绝不放过任何边界情况

    使用API开发应用,所能遭遇的最糟糕的情况,莫过于你发现了一个文档中没有提到的错误。如果你遇到这种情况,就意味着你不能确认究竟是你的程序出了错,还是你对API的理解出了错。

    因此,参考索引中必须包含每种假设可能造成的边界情况,不论是显示的还是隐式的。花点儿时间在这个上面,绝对能起到事半功倍的效果。

    7. 提供样例应用

    在学习结束的时候,开发者希望能看到关于项目产品应用的大致蓝图。达到这一目的最好的办法,莫过于提供可运行的样例应用。我发现,应用程序代码是将API运行机理和系统整合融会贯通最好的办法。

    sample code in Apple’s iOS Developer Library 则是这方面做得很好的,它包含了详尽的iOS样例程序,并按主题一一分类。

    8. 加入人性化的因素

    阅读技术文档枯燥乏味,自然不像坐过山车那样紧张刺激。不过,你至少可以通过加入一些人性化的因素,或者开开玩笑。给你的例子中的变量其一些好玩儿的名字吧,别老是把函数名称叫什么foo之类的,好让你的读者有焕然一新的感觉。

    至少,这可以保证你的读者不会读着读着就睡过去。

    结论:

    若要想深入人心,一个良好的设计文档必不可少。然而,设计一个好文档是需要大量投入才能形成的。但是,这些投入是值得的,因为它的意义和产品本身同等重要。

    编写良好文档的另一半诀窍,是要从产品开发的初始阶段就朝着这个方向努力。不过,这就不是本文讨论的范畴了。

     

    转载于:https://www.cnblogs.com/ssjie/p/4948035.html

    展开全文
  • 如何编写高大上的技术文档 作为程序员,除了会写代码,能查bug,还要会画图(UML建模)、做PPT(分享、述职等),更重要的是还要能写得出文档,并且能写出高大上的文档。 根据过往的经验,技术文档一般会: ...
  • 对改善软件技术文档编写很有帮助,可以下来看看
  • 如何编写高大上的技术文档作为程序员,除了会写代码,能查bug,还要会画图(UML建模)、做PPT(分享、述职等),更重要的是还要能写得出文档,并且能写出高大上的文档。根据过往的经验,技术文档一般会:项目文档:用于...
  • 如何编写一份清晰的技术实现方案文档
  • 中文技术文档编写规范,详细说明了文档如何编写,对从事技术的人大有裨益。
  • 程序员都很希望别人能写技术文档,而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版,想着新建的word文档放在哪个目录等各种非技术细节。 word文档零零散散地放在团队不同人那里,需要文档的...
  • 介绍如何编写技术解决方案。开发者在进阶过程中,总会遇到对一个完整技术和项目的设计和开发,此时需要从一个高的视角,审视对项目和技术的理解,该文档提供了一个思路或者方法
  • 架构设计文档的核心是以某种方式的选型决策,而开发团队可能不太清楚这个决策背后的假设和思考。 对于这些决策,由于我们缺少当时的上下文,只能盲目的接受和盲目的做出改变。 闲逛ThoughtWorks Radar偶然发现一个...
  • 编写技术文档,是令众多开发者望而生畏的任务之一。它本身是一件费时费力才能做好的工作。可是大多数时候,人们却总是想抄抄捷径,这样做的结果往往非常令人遗憾的,因为优质的技术文档是决定你的项目是否引人关注的...
  • 编写出优秀技术文档,要学会这四招 拥有准确的技术文档不仅对于公司是非常有益处的,而且也能够让客户从中受益。由于产品如何使用在某种程度上是要依赖技术文档来进行说明的,因此技术文档必须十分的准确可靠。...
  • 如何编写一个项目开发文档

    万次阅读 多人点赞 2018-09-29 21:51:31
    项目开发过程中为了增加程序的可读性和程序的健壮性, 方便后期程序的调试和维护,所以需要在开发过程中统一技术规范,一般会在项目初期确定好相关文档作为这一统一的规范。不同公司会对文档做不同要求,划不同的...
  • 由于产品如何使用在某种程度上是要依赖技术文档来进行说明的,因此技术文档必须十分的准确可靠。使用不准确的和已经过时的技术文档对于公司的发展也会产生一定的阻碍,同样的,它也会对公司的客户们产生消极的影响。...
  • 在工作中或者在发布开源项目时,需要编写技术文档,以便别人使用时,或者自己过了很久之后去看不会一脸懵逼。 我觉得写技术文档应该是一个程序员必备的技能,好的技术文档包括以下几个特性: 结构简单:将自己的...
  • Markdown技术文档编写规范

    千次阅读 2020-06-28 17:23:35
    Markdown技术文档编写规范 Markdown是一种可以使用普通文本编辑器编写的标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式。 文档体系 结构 简介(Introduction): [必备] [文件] 提供对...
  • 本文分为4个部分:为什么要写设计文档设计文档中应该包含哪些内容如何编写流程为什么要写设计文档设计文档 - 也被称作技术规范 - 描述了你计划如何去解决一个问题。已经有很多文章解释了编码之前编写设计文档的重要...
  • 软件验收文档清单 急于发布文档,您还有很多工作要做。 您可能会错过一些东西。 那可能是一个小东西,或者是一个大东西。 但是为什么要抓住这个机会呢?... 清单应该是任何技术作者工具包的一部分。 Atul Ga...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 904
精华内容 361
关键字:

如何编写技术文档