近期因爲老師的書要出版,需要修改內容錯誤和語義表達方面的問題.然而有些表述上的問題我不太會再加上之前我就不太愛說話,所以就很菜.現在發覺,說話其實也是一門挺深的學問,所以就學習一下關於技術文檔方面的寫作.
英語世界裏,文檔非常受重視,許多公司和組織都有自己的文檔規範,比如微軟、MailChimp、Apple、Yahoo、docker、Struts等等(維基百科有完整的清單).相比之下,中文的也有,但是大都不太令人滿意,要麼你太簡單,要麼不太適用.
一位大佬簡單整理的一份<中文技術文檔的寫作規範>
其中比較常見的一些:
1.如果使用了被動語態,就應該考慮更改爲主動語態
錯誤:假如此軟件尚未安裝.
正確:假如尚未安裝此軟件.
2.不使用非正式的語言風格
錯誤：Lady Gaga 的演唱會真是酷斃了，從沒看過這麼給力的表演！！！
正確：無法參加本次活動，我深感遺憾。3.用對"的","地","得"(注意詞義)
她露出了開心的笑容。
（形容詞＋的＋名詞）
她開心地笑了。
（副詞＋地＋動詞）
她笑得很開心。
（動詞＋得＋副詞）4.使用代詞時(比如"其","該","此","這"等詞),必須明確指代的內容,保證只有一個含義.
錯誤：從管理系統可以監視中繼系統和受其直接控制的分配系統。
正確：從管理系統可以監視兩個系統：中繼系統和受中繼系統直接控制的分配系統。5.名詞前面不要有過多的形容詞
錯誤：此設備的使用必須在接受過本公司舉辦的正式的設備培訓的技師的指導下進行。
正確：此設備必須在技師的指導下使用，且指導技師必須接受過由本公司舉辦的正式設備培訓。6.同樣一個意思,儘量使用肯定句表達,不要使用否定句表達
錯誤：請確認沒有接通裝置的電源。
正確：請確認裝置的電源已關閉。7.句子的長度儘量保持在20個字以內；20～29個字的句子，可以接受；39～39個字的句子，語義必須明確，才能接受；多於40個字的句子，在任何情況下都不能接受。
錯誤：本產品適用於從由一臺服務器進行動作控制的單一節點結構到由多臺服務器進行動作控制的並行處理程序結構等多種體系結構。
正確：本產品適用於多種體系結構。無論是由一臺服務器（單一節點結構），還是由多臺服務器（並行處理結構）進行動作控制，均可以使用本產品。8.儘量避免使用雙重否定.
錯誤：沒有刪除權限的用戶，不能刪除此文件。
正確：用戶必須擁有刪除權限，才能刪除此文件。原文地址:http://www.ruanyifeng.com/blog/2016/10/document_style_guide.html
