iT邦幫忙

0

請問要怎麼寫說明文件呢??

請問各位大大在軟體開發時~或者開發後~~
都是怎麼撰寫說明文件的呢??
是用哪種規範 or 軟體寫的嗎@@?

要怎麼寫"給一般使用者的說明文件"跟"給 IT 人員看的說明文件"
比較好呢?

或是其實 IT 產業已經有自己的一套標準流成了呢?

因為公司的開發人員只有我一個,
算是還在學習,也希望建立起來之後帶新人還是交接比較沒問題,
先謝謝各位~/images/emoticon/emoticon37.gif

newkevin iT邦高手 1 級 ‧ 2017-03-28 10:09:15 檢舉
軟體開發流程 關鍵字
先找看看有沒有類似的
如果不方便貼出你公司開發的架構
q00153 iT邦新手 5 級 ‧ 2017-03-28 10:26:19 檢舉
公司架構不會不方便貼出,
因為目前公司就軟體開發部份ㄜ.....沒有架構 QQ
0
huangsb
iT邦好手 1 級 ‧ 2017-03-29 07:38:27
最佳解答

以一個人開發來說,你提到的下列文件其實就夠了:

  • 一般使用者的操作說明
    • 這個文件通常會使用 Word 來製作,最好附圖解說明,最後才產出 PDF。
  • API 使用說明
    • 這個可以使用 API 文件產生器來產生
  • 專案架構說明
    • 這個就需要自己寫了,內容通常包含系統架構,每個系統包含的程式清單等等。

如果可以,當然還要包含系統建置及組態文件。系統建置文件說明了如何在新的環境中安裝你所開發的系統;組態文件則說明了那些設定檔是可因環境變動而修改的文件。

如果你夠認真的話,當然也要寫系統分析及設計文件,不過寫的好的人不多,因為常常會直接改程式,而忘了寫這樣的系統分析及設計文件,導致文件與程式不同步,也就失去製作文件的意義了。

0
souda
iT邦研究生 5 級 ‧ 2017-03-28 10:05:32

方便提供你想要寫的架構嗎?

q00153 iT邦新手 5 級 ‧ 2017-03-28 10:31:34 檢舉

回大大,
是希望說明文件包含
給一般使用者的操作說明 &
給程式開發人員的 API 使用說明 &
給接手的維護人員的專案架構說明 &
以上各個說明的 Q&A

因為要做的說明很多面,但是工時人力都不可能那麼多,
所以要訂定一個標準流程&有標準工具更好,
理想中當然是一邊開發一邊把說明文件完成,
雖然這不太可能 /images/emoticon/emoticon13.gif

0
牛哥
iT邦研究生 2 級 ‧ 2017-03-28 10:10:34

請問你是要寫Q&A、FAQ...之類的?
還是寫SOP?!

如果是寫Q&A,大概短短幾行敍述就結束。頂多再附上一個連結,給個更進階的說明網頁。
當然進階的說明網頁,你就多花心思,把操作過程的擷圖下來,加上註解就很豐富了~
要寫很大的話~有人甚至用WIKI來應對!

若是說明文件是SOP一類,那通常會有樣版參照。
較完整的架構,可以去參考ISO文件範例。
網路找找就很多囉~
加油~

PS/其實來IT邦多逛逛,技術問答的部份,就很像Q&A了。

q00153 iT邦新手 5 級 ‧ 2017-03-28 10:42:29 檢舉

/images/emoticon/emoticon22.gif
讓我想起從上一間公司離職的時候
為了交接程式還把操作部份分成好幾塊
錄了影片下來呢~ (因為用講的總是有代溝)

我是想寫 SOP 那一類,
希望訂個自己也不會覺得太麻煩,
而且有良好規範的說明文件建立方式,
可以省下未來很多工時,
哈哈

科技始終來自惰性

我再努力找找相關的文件範例看看
感謝大大

牛哥 iT邦研究生 2 級 ‧ 2017-03-28 10:45:36 檢舉

/images/emoticon/emoticon34.gif

0
海綿寶寶
iT邦超人 1 級 ‧ 2017-03-28 10:15:50

公司的開發人員只有我一個

除非你主管要求
否則不必寫說明文件

如果你還是想寫
只要寫好程式裡的註解說明
就功德無量了...

看更多先前的回應...收起先前的回應...
q00153 iT邦新手 5 級 ‧ 2017-03-28 10:37:41 檢舉

因為是開發公司內部的程式,
所以主管最多要求寫 操作手冊以及Q&A 給一般使用的同仁而已,
這部分目前都是用 Excel (萬能的 Excel~~)
平常的程式註解也是有的,

只是考慮到以後組織規模會變大,
而且總是用 Excel 也很不專業...

想要規劃一個工作流程跟規範,
以後帶新人就講解完規範就可以了,
交接不用幾天

目前是規劃到撰寫說明文件這部份,
不過因為太菜了
這方面不知道怎麼做才行/images/emoticon/emoticon33.gif

只要「使用的人看得懂,撰寫的人寫得順手」
就是好方法/好工具

如果只是把Excel換成Word
或是到Web介面填東填西的話
其實沒什麼太大好處

也可參考優秀邦友jamesjan的
好文

q00153 iT邦新手 5 級 ‧ 2017-03-28 10:57:14 檢舉

/images/emoticon/emoticon41.gif
看了該文章,發現了許多沒考慮到的東西,
感覺可以有個開始的依據了,感謝。

0
饅頭
iT邦新手 5 級 ‧ 2017-03-29 10:14:13

以我之前寫說明文件的經驗

  • 分類的方式是以「對產品的了解」
    • 對產品不了解的人:ex一般使用者
      建議是「圖文並茂」,文字說明 圖片輔助

    • 對產品了解的人
      給文字步驟就看得懂了

  • 事前工作、事後使用
    • 事前的設定等等,就不需要給一般使用者看到-->"給IT人員看的說明文件"
    • 事後使用教學-->"給一般使用者看的說明文件"

如果是說明書的話我會用 PPT (圖片好拉,大小設定A4)
排版清楚也很重要

要怎麼看出成功的"給一般使用者看的說明文件"?
拿給一個不懂的人看就知道了XDDD/images/emoticon/emoticon01.gif

我要發表回答

立即登入回答