Thursday, January 16, 2020

用 Event Modeling 的方式來描述規格

如何描述規格?

我做軟體做好幾年了,寫程式換過幾種語言。而寫規格書,卻沒有下過功夫去研究。最近一次開發一個比較大的系統,我自己後來寫出來的規格書,大概包含了三個部分:

1. 用講故事 (story telling) 的方式,用人類語言敘述的系統行為。 
2. Database 的 schema 
3. API 的 spec 

後來,仔細想想,這樣子其實也是有問題。其實一個系統的開發,應該拆解成三個階段:
A. 用「非開發人員」也可以理解的方式,書寫的高階系統行為、概述。講的是系統的目的 (purpose)
B. 以程式語言實作系統 (implementation)
C. 寫出該系統的實作規格 (description of implementation)

以我自己的最近一回做的東西來講,story telling 算是 A 。Database schema 和 API spec 都是 C。而系統在與非開發人員溝通,主要是依賴 A 的部分。換言之,其實我做 A 的部分,算是做得很不清楚,因為只有 story telling ,算是相對難以把事情說清楚的。

Event Modeling

Event Modeling 該網站提出的方法,我覺得算是 story telling 的加強版,即 story telling with time。它建議,首先畫一條水平軸,描述「時間」的進展,然後以:
1. Wireframes 描述「使用者介面」
2. Swimlanes 描述「不同的使用者」或「不同的外部系統」的關注點
3. User story   描述 event, command, view 的關系。User story 使用 Given-When-Then 的形式來寫。

系統的 state 與人或是其它外部系統互動的方式,又可以仔細區分成 4 種 patterns
1.  Command  - state change
2.  View           - state view
3.  Translation - external state input
4.  Automation - external state output

Monday, November 11, 2019

使用 Datomic 要注意的事: should not expose the entity number

偶然在 stackoverflow 上,看到了這類相關的問題

When design the system API, it's very important that your input never have any raw entity ids in it, only external ids. Below is the reason:
  1. You don't have an entity id until you transact the entity, so you can't create an entity and all its indexes together. You must first transact the entities, see what their entity ids were, then transact the composite index. 
  2. It's no longer easy to do your own renumbering. There are datomic techniques which involve taking datoms from one database and transacting them to another, or recreating a db from its datoms or transaction log. The reason these techniques work fairly easily and robustly is because all pointers (refs) are known and can be renumbered. If you store an entity id in a value, you now need more complicated schema-specific logic to re-transact the datoms correctly.
  3. Cognitect has said not to rely on stable entity ids because they haven't ruled out the possibility of renumbering them in the future. Right now, however, no renumbering occurs, but I would rather not tempt fate.


Thursday, October 24, 2019

nREPL debug


最近研究透過 nREPL 來除錯,發現有幾個重點

1. 透過 nREPL 可以連上 running process ,考慮安全性,通常 nREPL 只監聽 127.0.0.1
2. 如果要在 local 端開 vim 除錯,就得用 ssh 做 local port forwarding
3. 很常見的情況是,deployment machine 不可以用 ssh 直接連上 ,因為中間還又卡一個 kerberos 機。
    這樣子的話,解法還有兩種:
    (a) 我個人會採用的,是直接把 vim, vim-fireplace 灌在 deployment 機上  
         https://github.com/humorless/dotfiles/issues/8
    (b) 使用 DrawBridge

Tuesday, October 8, 2019

Company of One book review --- 「技能與可行性測試」

書名:「一人公司」
作者:Paul Jarvis


「成長是導致許多初創企業失敗的主要原因,甚至包含很多頂級企業也是。」

「足夠是成長的相反。」

「衡量成功的標準不應該是季度利潤的增加、不斷成長的新客戶取得、或是成功的退場策略(exit strategy)。相反的是,我們可以專注於「生存策略」(exist strategy) --- 以堅持、盈利,以及盡力為客戶提供服務為基礎。」

我最欣賞的段落,節錄如下:
「多數成功的商業人士在進行主題演講時,當他們在分享他們有多明智,選擇投入更充滿熱情的工作生活時,我注意到他們沒有談論到兩個關鍵因素。第一,他們在投入之前就對他們自己所做的事很熟練,而且這些技能非常搶手。第二個遺漏的關鍵因素是,他們在攀登到最高的舞台之前,他們能夠先跨出一小步,為自己即將跨出的一大步試水溫。(確保他們提供的東西有足夠的需求。)」

這個經典的段落談了創業的關鍵要素:技能可行性測試

Monday, September 30, 2019

TREVOR JIM blog 啟發

快速地掃了近十篇在 TREVOR JIM blog 上的文章,覺得也滿有啟發的。

比方說:
1.  Remote work is a moon shot. (大家用 remote work 就好,比自動駕駛車好多了)
2. 應該用停用 C/C++ ,因為這類的語言對 security 是一大傷害。應該要用 memory safe 的語言。
3. Parsing is the weakest link in software security. Parsing security 甚至比 buffer security 更重要!

Tuesday, September 24, 2019

Clojure made simple / What is good software?

Clojure made simple 是 Rich Hickey 用來解釋 Clojure 的 value proposition 的一部影片,仔細看過之後,我覺得影片一開始 10 分鐘的分析,非常的深刻。它提供了 Rich Hickey 對於 good software 的看法。

開頭沒有多久,Rich Hickey 就提到寫程式是一種 economic activity ,換言之,你是有雇客或是老闆的。那…雇客/老闆要什麼?他們要的東西就是兩件事:
(1) Something good
(2) Soon

那怎樣子的軟體算是 Something good 呢?定義該是什麼?Rich Hickey 定了三個條件:(Rich Hickey 有特別去強調, type 或是 tests 只是達成目標的手段之一,不能成為目標的定義。)
(a) Does what it is supposed to do
(b) Meets operational requirements
(c) Is flexible enough to accommodate change

然後,這三個 good software 的構成條件又可以拆解開來:
首先對於 (a)
It is very difficult to determine if large or elaborate or stateful programs do what they supposed to do.
而 Clojure 設計的目標之一,就是 making it easier to understand whether or not your program is going to do what it is supposed to do by making it substantially smaller and also by making it more functional.

對於 (b) ,有下列三個目標:
=> 1. Deployment/environment
=> 2. security
=> 3. performance
Clojure 可以透過 host 在 Java/Javascript 上來達成。

對於 (c) ,達成目標的重點在於 loose coupling

Monday, September 2, 2019

Million Dollar Consulting book review


書的最初就有提到,要做到 million dollar consulting,通常有三個條件。 
條件一:要賣 process expertise 而非單純的 context expertise 
條件二:要 paid by project ,而不是 paid by hour 
條件三:要有滿滿的 sales pipeline ,要接的單可以直接排滿 12 個月。 

以下是初步的心得總整理,只看了 1/4 。 

(1) 個人網站,隨便做,放個基本介紹即可。 
Why? consulting 要開發業務的話,比較有效的方式,是要透過人與人的接觸,才會有足夠的信任感,讓客戶考慮你。準備網站,只是讓客戶要查資料時,更產生信心而已。如果要把網站做到可以說服客戶直接下單、要做一堆 SEO ,這樣子的成本太高了。 

(2) 書中有提了許多強化 marketing gravity (行銷吸引力),但是,Alan Weiss 毫不猶豫地提到,初期會有效的招式,只有 speaking, networking, referrals 這三招而已。這三招都是有人與人直接面對面的招式。 

(3) 書裡有一個章節在教 proposal 。Alan Weiss 主張,如果你的 consulting 幫客戶創造十元的價值,你應該要在 proposal 裡把這件事寫出來。並且在 proposal 裡寫,我要 charge 1 元。作者還寫了一本 Million Dollar Proposal 

=> 我個人的看法,這種 aggressive proposal 勢必需要 extreme high quality work 才能搭配。 

(4) 書中主張,要做 consulting 的生意,要隨著時間,labor (勞動)愈來愈少、但是 fee (收費)愈來愈高。其中,業務開發 (acquisition) 就是一種巨大的勞動。而 referrals 可以有效地降低 acquisition 的 labor 。 referrals 就是一種極為重要的業務開發槓桿,而書中也有專門的章節談 referrals 的技巧。作者還寫了一本 Million Dollar Referrals。 

(5) 營收的成長模型 
作者認為,每年應該追求 80% 的 repeat business 與 20% new business 。同時,每 18 個月,淘汰品質最差的 15% 的營收。 

(6) 利潤的分配 
如果說,consulting business 有跟 partner 組隊開發。作者認為,功勞 (也就是利潤)的分配應該如下: 

Acquisition = 50%, Methodology = 30%, Delivery = 20% 

原文如下: 
If you find yourself allied with someone in acquiring and delivering business, here's an objective formula to apply so that all parties are treated equitably: 

Acquisition = 50%, Methodology = 30%, Delivery = 20% 

This means that if I acquire the business (50 percent) and we use your methodology (30 percent) and split the delivery (20 percent), then the total fee would be split like this: 60 percent me, 40 percent you. This reflects the various importance of the three elements involved in sharing business. Note that this does not apply to people who solely deliver. They should be paid a daily rate plus expenses. At this writing, excellent delivery people (training, facilitating, focus groups, assessment work, interviewing, and so forth) can easily be obtained for $1,000 per day.