2020年10月

【转】编写项目文档时要问自己的 5 个问题

使用有效沟通的一些基本原则可以帮助你创建与你的品牌一致的、编写良好、内容丰富的项目文档。

在开始实际撰写又一个开源项目的文档之前,甚至在采访专家之前,最好回答一些有关新文档的高级问题。

著名的传播理论家 Harold Lasswell 在他 1948 年的文章《社会中的传播结构和功能》中写道:

(一种)描述沟通行为的方便方法是回答以下问题:

  • 说什么
  • 在哪个渠道
  • 对谁
  • 有什么效果?

作为一名技术交流者,你可以运用 Lasswell 的理论,回答关于你文档的类似问题,以更好地传达你的信息,达到预期的效果。

谁:谁是文档的所有者?

或者说,文档背后是什么公司?它想向受众传达什么品牌形象?这个问题的答案将极大地影响你的写作风格。公司可能有自己的风格指南,或者至少有正式的使命声明,在这种情况下,你应该从这开始。

如果公司刚刚起步,你可以向文件的主人提出上述问题。作为作者,将你为公司创造的声音和角色与你自己的世界观和信念结合起来是很重要的。这将使你的写作看起来更自然,而不像公司的行话。

说什么:文件类型是什么?

你需要传达什么信息?它是什么类型的文档:用户指南、API 参考、发布说明等?许多文档类型有模板或普遍认可的结构,这些结构为你提供一个开始的地方,并帮助确保包括所有必要的信息。

在哪个渠道:文档的格式是什么?

对于技术文档,沟通的渠道通常会告诉你文档的最终格式,也就是 PDF、HTML、文本文件等。这很可能也决定了你应该使用什么工具来编写你的文档。

对谁:目标受众是谁?

谁会阅读这份文档?他们的知识水平如何?他们的工作职责和主要挑战是什么?这些问题将帮助你确定你应该覆盖什么内容,是否应该应该涉及细节,是否可以使用特定的术语,等等。在某些情况下,这些问题的答案甚至可以影响你使用的语法的复杂性。

有什么效果:文档的目的是什么?

在这里,你应该定义这个文档要为它的潜在读者解决什么问题,或者它应该为他们回答什么问题。例如,你的文档的目的可以是教你的客户如何使用你的产品。

这时,你可以参考 Divio 建议的方法。根据这种方法,你可以根据文档的总体方向,将任何文档分为四种类型之一:学习、解决问题、理解或获取信息。

在这个阶段,另一个很好的问题是,这个文档要解决什么业务问题(例如,如何削减支持成本)。带着业务问题,你可能会看到你写作的一个重要角度。

总结

上面的问题旨在帮助你形成有效沟通的基础,并确保你的文件涵盖了所有应该涵盖的内容。你可以把它们分解成你自己的问题清单,并把它们放在身边,以便在你有文件要创建的时候使用。当你面对空白页无从着笔时,这份清单也可能会派上用场。希望它能激发你的灵感,帮助你产生想法。


via: https://opensource.com/article/20/9/project-documentation

作者:Alexei Leontief 选题:lujun9972 译者:geekpi 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

MySQL创建数据库与创建用户以及授权

1、create schema [数据库名称] default character set utf8 collate utf8_general_ci;--创建数据库
采用create schema和create database创建数据库的效果一样。

2、create user '[用户名称]'@'%' identified by '[用户密码]';--创建用户
密码8位以上,包括:大写字母、小写字母、数字、特殊字符
%:匹配所有主机,该地方还可以设置成‘localhost’,代表只能本地访问,例如root账户默认为‘localhost‘

3、grant all privileges on [数据库名称].* to [用户名称];--用户授权数据库
*代表整个数据库

4、flush privileges ;--立即启用修改

5、revoke all on . from tester;--取消用户所有数据库(表)的所有权限

6、delete from mysql.user where user='tester';--删除用户

7、drop database [schema名称|数据库名称];--删除数据库

浅析设计模式-迪米特法则

迪米特法则的英文名称是 Low of Demeter,简称LoD。也称为最少知识原则(Least Knowledge Principle,LKP)

定义

一个对象应该对其它对象有最少的了解。通俗的讲,一个类应该对自己需要耦合或调用的类知道的最少,你(被耦合的类)的内部是如何的复杂都和我没关系,我只知道你提供的public方法,我就调用那么多,其它的一概不管。

含义

迪米特法则对类的低耦合提出了明确的要求,包含一下含义:

  • 只和朋友交流
  • 朋友间也是有距离的
  • 是自己的就是自己的
  • 谨慎使用Serializable

最佳实践

迪米特法则的核心观念就是类间解耦,弱耦合,只有弱耦合之后,类的复用率才可以提高,其要求的结果就是产生了大量的中转或跳转类,导致系统的复杂性提高,同时也为维护带来了难度,采用迪米特法则时需要反复权衡,既做到让结构清晰,又做到高内聚迪耦合。

浅析设计模式-接口隔离原则

接口隔离原则的英文名称是 Interface Segregation Principle,简称ISP。

定义

接口分为两种:

  • 实例接口(Object Interface),在Java中声明一个类,然后用new关键字产生一个实例,它是对一个类型的事物的描述,这是一种接口
  • 类接口(Class Interface), Java中经常使用的interface关键字定义的接口。

隔离有两种定义:

  • Clients should not be forced to depend upon interfaces that type don't use.(客户端不应该依赖它不需要的接口。)
  • The Dependency of one class to another one should depend on the smallest possible interface.(类间的依赖关系应该建立在最小的接口上)

可以把这两个定义概括为: 建立单一接口,不要建立臃肿庞大的接口。通俗一点:接口尽量细化,同时接口中的方法尽量少。

保持接口的纯洁性

接口隔离原则对接口进行规范约束,包含一下含义:

  1. 接口要尽量小
  2. 接口要高内聚
  3. 定制服务
  4. 接口设计是有限度的

最佳实践

  1. 一个接口只服务于一个子模块或业务逻辑
  2. 通过业务逻辑压缩接口中的public方法,接口时常去回顾,尽量让接口达到“满身筋骨肉”而不是“肥嘟嘟”的一大堆方法
  3. 已经被污染了的接口,尽量去修改,若变更的风险较大,则采用适配器模式进行转化处理
  4. 了解环境,拒绝盲从

浅析设计模式-依赖倒置原则

依赖倒置原则的英文名称是 Dependence Inversion Principle,简称DIP

定义

High level modules should not depend upon low level modules. Both should depend upon abstractions. Abstractions should not depend upon details. Details should depend upon abstractions.

- 阅读剩余部分 -