Re: [請益] 請問寫文件的訣竅

[qwerty0981 ([e-mail])]

※ 引述《et282523 (不屈鬥志)》之銘言：
: 各位朋友及前輩
: 請教一下各位寫文件的時候，有沒有什麼訣竅？
: 小弟目前正在寫一些說明文件，但發現很難理出一個頭緒
: 我正在寫的是程式架構和流程的說明
: 雖然那個程式的架構是我設計及實作出來的
: 不過因為有點複雜，細節有點多
: 搞到自己寫文件都不知該怎麼下手
: 雖然也不是沒寫文件同事就無法理解
: 但因為是自己寫出來的架構，很想把自己的想法寫的清楚一點
: 也讓未來新進來的同事可以更快的熟悉這個架構
: 不知道前輩們有沒有什麼建議，寫文件真的好痛苦啊？
: 好想趕快把文件寫完繼續寫 code 啊...

請問，

您的說明文件是包含這隻程式如何create的idea，

還是僅解釋程式架構和workflow等呢？

如果是學生等級的文件，其實structure和flow有出來就可以了。

如果是業界等級的文件，可能向您的學長姐有在工作的借一份spec比如DFD參考。

如果是經典書籍的等級的文件，可能在文件開頭要包含您create的idea的小故事。

大概這樣吧，如還有需要幫忙，

請站內信qwerty0981，讓吾幫您補個卦。


--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 220.135.203.156
※ 文章網址: http://www.ptt.cc/bbs/Soft_Job/M.1417583840.A.4F6.html
推 WisdomOrLie: 今天是花生蛇麼事ㄇ
我很認真回文耶，WisdomOrLie

您，累了嗎？

※ 編輯: qwerty0981 (220.135.203.156), 12/03/2014 13:28:36
→ et282523: 是工作上的文件啦，不過公司並沒有要求，只是寫給同事
→ et282523: 看的，而且我功力一般般，沒有很強啦，只是不太會寫文件
→ qwerty0981: 寫給同事的就是上面我寫的第二句吧。意思是說
→ et282523: 公司並沒有要求要寫文件，所以只是容易理解就可以了
→ qwerty0981: 先求助看有沒相關參考文件，然後用自己的方式揣摩寫出
→ et282523: 感謝這位大大！
沒的事，祝福您。
※ 編輯: qwerty0981 (220.135.203.156), 12/03/2014 13:34:55
推 wheattea: 也要考慮接手人的程度 才知道內容是要給新手還是老手看
我持相對意見。


接手人的程度是一點，但不宜被接手人的程度影響自己寫作的內容深度。

即使接手人目前程度不能完全參透，

只要保有文件，多看幾遍 或 假以時日他/她再回頭閱讀，

因接手人的功力進步後，文件自然就派上用場了。


當然，接手人現在看不懂會問問題，那就請原po據實以答就可以了。

怎麼拿捏，如何平衡，每個人都會的，沒有佛山無留手的問題。

※ 編輯: qwerty0981 (220.135.203.156), 12/03/2014 18:19:01
推 wheattea: 因為原po說希望新進同事更快熟悉架構
→ wheattea: 如果寫一份新進人員看不懂的文件就失去原po的初衷了
嗯，我了解您的意思了，的確是。

→ et282523: 其實我覺得沮喪的事，感覺寫 code 比較容易，要文件反而
→ et282523: 寫不出來！明明都是自己做的東西，才想來問有沒有訣竅
→ et282523: 或許真的沒什麼捷徑吧，我試看看硬寫一份出來，再慢慢修
→ et282523: 改好了。
→ et282523: 更正：沮喪的"是"
努力努力，

先有大概(大綱)再修改也不失為寫作的第一條路之一。

→ keyboard56: 自己的還算好寫吧，寫別人的才會知道相對不好下手
※ 編輯: qwerty0981 (220.135.203.156), 12/04/2014 04:28:38