談行文邏輯(10.3)

最近臨近專案上線，國慶第3天，加班進行中。當前最主要的工作仍然集中在上線前的風險進一步識別和分析，上線前的檢查單整理和檢查，以及線上幫助類文件的整理。

今天開始將已有的標準規範類Word文件整理為MarkDown格式檔案，在整理過程中發現不是簡單的通過上篇文章介紹的工具將Word文件轉換為md文件就可以，而是發現在文件編寫和行文上存在較大差異。

即線上幫助文件更多要解決的問題是業務系統自服務使用，即完全可以看線上幫助內文件實現自服務，不需要任何的人工解答和幫助。而我們傳統的標準規範類文件，很多則是我們方案宣講後提供的一個輔助文件，同時文件本身不一定很細，很多還是需要在專案實施過程中進行解答。這就導致了原有的規範文件文件簡單轉換後，如何業務系統自己檢視該文件，在沒有經過前期方案宣講和培訓的情況下，很難真正能夠明白文件內容。

大家可以看下對於當前的各類公有云IaaS平臺和PaaS平臺，包括各類物聯網的開放能力平臺，各類電商的OpenAPI平臺，為了提供相應的服務能力，往往會提供完整的服務開發，服務接入和消費的指導文件和手冊。這些文件相當詳細，基本都是達到Step By Step的程度，同時還提供大量的API線上手冊，參考示例程式碼供檢視，這些都幫助使用者能夠快速的完成各類自服務。要知道面對成千上萬的註冊使用者，如果都要通過大量的人工服務來進行答疑和解決問題，將會耗費巨大的人力資源成本。

只要一個流程足夠標準，一個方法或技術足夠規範，那麼就一定可以制定詳細的幫助手冊和自服務文件，這個文件的目的就是完全實現自服務，只要你有一定的技術基礎，你完全按照文件步驟進行操作就能夠完成工作。

要實現這個目標，我們在行文上就必須注意，要時刻想著如果你是使用者，同時沒有相應的前期背景知識積累，看了文件後是否能夠真正明白如何做？寫幫助文件的目的是讓使用者看懂，而不是你自己看懂。如果一個線上文件給到使用者後，使用者還經常有大量的問題和疑問反饋過來，那麼往往就代表文件還沒有足夠細。

我們有時候寫文件包括我們開發系統都容易假設使用者具備一定的業務和技術基礎，但是往往面對千差萬別的使用者群體，這個假設往往都是不成立的，你完成的文件和功能必須具備一定的通用性和普適性。

基於以上思考，在寫這類文件的時候，行文的關鍵就在於要以業務或技術場景，問題驅動來整理文件。

比如當你面對一個業務場景或問題的時候，你究竟該如何做？那麼我提供一個Step By Step的文件給你，你只需要安裝步驟做就可以了。比如一個業務系統需要消費整合平臺提供的WS服務，那麼究竟該如何做？

在行文的時候首先就應該將整個服務消費和訂購流程說清楚，然後再對流程中的每一個活動究竟如何做，有哪些注意事項都說清楚即可。如果涉及到程式碼的，你還可以提供相應的程式碼案例參考，能夠提供流程圖的提供流程圖，能夠提供架構圖或示例圖的就提供示例圖以方便使用者理解。

這種行文可以減少一些學術化的技術詞彙，而是儘量淺顯易懂的把事情描述清楚，描述的越直白越好。對於這類自服務的文件，最好的效果就是使用者只需要照著步驟做，而不是自己思考該如何做。

回顧下自己部落格文章寫作，往往也是同樣的道理，對於很多技術文章，我寫作的目的往往是個人存檔和記錄，自己經驗的總結，採用的更多的是歸納方法，因此這類文件沒有經歷相同技術問題的讀者往往很難理解文章的內容。如果好的技術經驗積累真正要分享的畫，那麼行文的方式則會發生重大的變化，即更多的是採用場景或問題驅動的方式，來演繹整個問題解決過程，一開始就開門見山，在演繹完後再進一步歸納總結，這樣往往才能夠達到經驗分享的效果。