DEV Community: abser

如何编写像 Google Doc 一样的文档

abser — Sat, 29 Aug 2020 06:59:28 +0000

基础部分

使用术语

术语使用要保持前后一致
缩略词第一次出现应为 Telekinetic Tactile Network (TTN) 形式
使用术语全称还是缩略词需要考究.
重用名词而不是使用代词.(就像指针一样, 代词往往会引入错误和歧义) ~~This, That, It, Them~~

使用主动语态(谁对谁做了什么)

大多数人的思维方式是主动语态, 可以帮助读者跳过预处理器阶段,直接进行编译. 并且主动语态更短. 被动语态有时会省略 actor.

错误例子
- It has been suggested that...
- Data was taken...
- Statistics were calculated...
- Results were evaluated.

消除句子歧义

使用准确的动词

The error ~~occurs~~ when clicking the Submit button.
💡Clicking the Submit button triggers the error.

This error message ~~happens~~ when...
💡The system generates this error message when...

We ~~are~~ very careful to ensure...
💡We carefully ensure...

去掉 There is, There are

~~There is~~ a variable called that stores the current accuracy.
💡A variable named stores the current accuracy. The variable stores the current accuracy.

~~There is~~ no guarantee that the updates will be received in sequential order.
💡**Clients **might not receive the updates in sequential order.

减少形容词和副词

Setting this flag makes the application run screamingly fast.
💡Setting this flag makes the application run 225-250% faster.

google doc 在这里说, 减少副词会减少语言魅力, 换成数据可以增加可信和准确度, 是值得的. 我认为可以折中一下.
💡Setting this flag makes the application run screamingly faster(225-250%).

将长句分割成短句

直接分割

The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.
💡The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.

给读者选择阅读的权利

To alter the usual flow of a loop, you may use either a **break **statement (which hops you out of the current loop) or a **continue **statement (which skips past the remainder of the current iteration of the current loop).
💡To alter the usual flow of a loop, call one of the following statements:

break, which hops you out of the current loop.
continue, which skips past the remainder of the current iteration of the current loop.

减少多余的词

An input value greater than 100** causes the triggering of logging.
💡An input value greater than 100 **triggers logging.

✅one sentence = one idea 记住这个原则

列表语义统一

区分顺序和无序列表
列表每一项应为统一格式
解释列表的含义

段落

写作的工作很简单：解开主题部分之间的依赖关系，并在逻辑流中呈现这些部分，使读者能够理解您。

使用总分句式A block of code is any set of contiguous code within the same function. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.
💡A loop runs the same block of code multiple times. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.
使每段话保持一个主题, 与主题无关的应该舍弃The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse. ~~The perimeter of a triangle is equal to the sum of the three sides.~~ You can use the Pythagorean Theorem to measure diagonal distances. For example, if you know the length and width of a ping-pong table, you can use the Pythagorean Theorem to determine the diagonal distance.~~ To calculate the perimeter of the ping-pong table, sum the length and the width, and then multiply that sum by 2.~~

不要太长或太短(这个我觉得保持在 3 到 5 句话就合适, 见仁见智)
问自己三个问题来优化段落表达
1. 你要告诉读者什么
2. 为什么这一点需要读者知道
3. 读者怎么使用你告知的信息, 或者读者如何知道你说的是正确的.

💡 The garp() function returns the delta between a dataset's mean and median. Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily influenced by a few very large or very small data points. Call garp() to help determine whether a few very large or very small data points are influencing the mean too much. A relatively small garp

受众

良好的文档= 受众完成任务所需的知识和技能 – 受众当前的知识和技能
确立受众角色, 斟酌使用术语,习语, 并为读者提供可查阅的资料如果需要.

文档

确立文档范围 本文档介绍了 Frambus 项目的总体设计
说明受众期望本文档假定您了解矩阵乘法以及如何泡一杯茶
简单摘要 比如简介比如大纲
确立文章预期 读者阅读之后期望得到什么知识和技能

提高部分

提高部分主要讲述了一些策略用于优化文档. 斟酌选用他, 并持续保持

采用样式指南, 比如让写作者统一学习上面的基础部分.
在受众的角度来审阅文档 - 该策略可能会为受众增加指向资源的链接, 让他们可以了解更多信息
大声朗读 - 可以避免不自然的措辞, 长句
初稿后间隔一段时间( hours ) 再回来改进迭代

组织大型文档

选择类型, 是单个大文档(像这篇文章) 还是一组文档(就像这篇文章使用的 Google Writing 教程)

整一个大纲
优化标题表达
逐步提供信息 (不要一股脑把所有的概念贴在开头)

画图

figures truly worth a thousand words.
这是最重要的部分, 首先图片的吸引力比文本大, 也能让读者学到更多. (这个教程说大多数成年人在面临技术文档的时候还是小孩子, 他们更渴望图片.

给图片标题
限制单个图片信息量
突出重点聚焦注意力
不断迭代
- 询问自己问题
  - 如何简化插图？
  - 我应该将此插图拆分为两个或更多更简单的插图吗？
  - 插图中的文字容易阅读吗？文本是否与其背景形成足够的对比？
  - 要点是什么？

例子代码

提供正确的, 简短的, 可重用的代码, 同时保证代码带来的副作用最小

Show Our Opensource Contributions on ObserveableHQ or any Website.

abser — Wed, 26 Aug 2020 10:32:33 +0000

Hello there. Today I'll bring you the dynamic opensource contributions display table.

Let's see first.

live demo

Overview

Github API could provide us the PullRequest info or others. Call the API on the ObserveableHQ Website and show the info as a table view.

ObserveableHQ is an online book to think with data. You could run js code on it and analytic data.

Step

Configure Github

we first use the github3 API library on ObserveableHQ

import { viewof ghKey,github3 } from '@yhyddr/github-api-in-observable-v3-and-v4'

ghKey give us the power to request info from github.com. and we store it as a secret: the concept of ObserveableHQ, so the secret would not expose to everyone.

generate the token at your github.com.

then fill the input box and click set secret.

Now you could request GitHub API with this library!🎉

PR = github3`search/issues?q=author:abserari+type:pr`

PR variable value would contain the PR info of the user: abserari.

Work with data.

First import the table so we don't need to type manually to fill the info.

import { table } from "@gampleman/table"

use table to map the PR entries to a table

table(DisplayPR, {
  nully: () => '<span style="color: red">No data</span>',
  limit: 500,
  enableFilter: false,
  enableCSVDownload: true,
  columns: [
    {
      key: 'repo',
      name: 'Repo',
      render: val => `${val}`
      // `<a href="https://google.com/?q=${val}" target="_blank">${val}</a>`
    },
    {
      key: 'statusHTML',
      name: 'Status',
      render: val => `${val}`
    },

    {
      key: 'checksHTML',
      name: 'Checks',
      render: val => `${val}`
    },
    // 'body'
    {
      key: 'content',
      name: 'Content',
      render: val => `${val}`
    }
  ]
})

we would get the dynamic table on ObserveableHQ!

Could download the js file and embed it to yourselves app.

You also could fork my notebook and configure it with your GitHub token.

Introduction to Dapr Source Code With a Pub-Sub Sample

abser — Mon, 24 Aug 2020 08:57:52 +0000

Introduction to Dapr Source Code With a Pub-Sub Sample

Overview

Hello guys, I'll tell you about the Dapr's source code. Dapr is a distributed application runtime. On its official website. It's introduced as: An event-driven, portable runtime for building microservices on cloud and edge. I have followed Dapr for almost one year. When it was published to the public, I wrote two blogs to introduce how I got familiar with Dapr and recorded my steps.

Today, I'm curious about how Dapr have these features: portable, event-driven, etc. so I dig into the source code and wonder if I could learn something from its architecture.

I drew some pictures and stored them here. Hope they are helpful.

Below we would run a sample called pub-sub sample and explain how the components like pub-sub could be portable to Dapr.

Prerequisites

We need to get Dapr installed. If not, follow https://dapr.io/ or my blog. If you have Mac

$ curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | /bin/bash

 $  dapr init
⌛  Making the jump to hyperspace...
    Downloading binaries and setting up
    components
✅  Success! Dapr is up and running

hint: you should have docker installed, too.

Get the code

$ git clone https://github.com/abserari/go-sdk

I wrote a simpler example in https://github.com/abserari/go-sdk/example/pubsub

SDK-Source Code

Configuration

In the configuration, we specify the metadata of the component, like our pub-sub component below:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: messagebus
spec:
  type: pubsub.redis
  metadata:
  - name: redisHost
    value: 192.168.0.253:32220
  - name: redisPassword
    value: "123456"

name: messagebus

Dapr needs the name to configure the API

spec:

This config is to init the components so Dapr could connect.

Pub.go

After we init the Dapr runtime. we could use pub-sub with go-sdk quickly.
We use this function to publish data to target pub-sub components with pubsubName and specific topicName.

client.PublishEvent(ctx, pubsubName, topicName, data)

Sub.go

It's a little unfamiliar with the way of subscribing to Dapr. you should have a server with some handler to tell Dapr runtime what topic you care about and how to notify you with the specific route when Dapr has a message to publish to the topic your concern.

config subscription

var sub := &common.Subscription{
    PubsubName: "messagebus",
    Topic:      "neworder",
    Route:      "/orders",
}

add to server

if err := s.AddTopicEventHandler(sub, eventHandler); err != nil {
    log.Fatalf("error adding topic subscription: %v", err)
}

Run

This https://github.com/abserari/go-sdk/example/pubsub folder contains two go files that use this go-SDK to invoke the Dapr PubSub API.

Helpful

Steps

Preparation

Get dapr installed

Run Subscriber Server

When we use Dapr PubSub to subscribe, we should have an http or gRPC server to receive the requests from Dapr.
Please change directory to pubsub/ and run the following command:

dapr run --app-id sub \ 
         --app-protocol http \ 
         --app-port 8080 \ 
         --port 3500 \ 
         --log-level debug \ 
         --components-path ./config \ 
         go run sub.go

Run Publisher

Publish is more simple than subscribe. Just Publish the data to target pubsub component with its' name.
After you start a server by above guide. Please change directory to pubsub/ and run the following command:

dapr run --app-id pub \ 
         --log-level debug \ 
         --components-path ./config \ 
         go run pub.go

Result

You would see the log that in the terminal which runs the server(subscriber) code.

== APP == 2020/08/23 13:21:58 event - PubsubName: messagebus, Topic: demo, ID: 11acaa82-23c4-4244-8969-7360dae52e5d, Data: ping

Dapr Source Code

Registry

We have to know about the Dapr runtime in the real world. then we tell about how Dapr runtime registers the components.

It's an interface in Dapr source code and the different realize of components is in github.com/dapr/components-contrib.

Then Dapr has a registry struct to store the method that use to new a component instance.

Runtime

When we run the dapr. runtime init all the components with YAML files in your path. if in Kubernetes mode, it would read the yaml from Kubernetes.

I'm happy to chat with your question on dapr or this article. Please comment or contact me.