iT邦幫忙

DAY 10
9

IT上櫃心法系列 第 10

[IT上櫃心法]-9.系統文件

每一家公司針對業務與營運上的需求,對於現行運作中的系統多少都會有功能的調整與新增,由於人員可能異動,或系統可能大幅調整,如果文件沒有跟著更新,隨著人員的異動,久而久之就沒有人曉得當初是為了什麼原因而進行調整的(這也是現在檢討流程時的困擾)。

稽核重點:重大需求變更是否更新系統相關文件。

提供資料:系統相關文件(使用手冊、操作手冊、SOP、教育訓練文件等)
我曾經這樣想過,如果有一套完美的系統,這樣所有系統的問題都迎刃而解,程式開發人員也不用這麼辛苦了開心

這麼多年下來,我發現夢終究還是夢,IT依然是挨踢...XD...這就跟每個男人都希望擁有一個完美情婦(誤)完美嬌妻一樣...啊...我的補教人生...咳...回歸主題

寫文件、寫手冊,相信一定是程式開發人員的夢靨,為什麼程式要愈寫愈簡潔,而文件卻要愈寫愈厚重?誰會看?誰又想看呢?

可是如果你問剛進公司的新人,他最需要的是什麼,他一定回答你系統的使用文件或Help哈哈

這就是程式開發人員與使用者間的鴻溝,如何將程式運作的邏輯讓使用者可以很容易的了解,這就是我們製作文件的目的。

那麼,文件的內容應該包含哪些呢?與其天馬行空,隨興而寫,不如遵循一些基本的原則,讓文件的可讀性提高,這樣文件的製作才有意義與價值。

當然要花多少時間製作文件,可能見仁見智。但文件能否被妥善的管理,則就相形重要了。

首先,我們從文件的封面看起。(謎之音:封面不就是文件標題?)如果是這樣,就太粗淺了!除了文件標題,應該還有文件的版本、發行日期、文件的狀態(如 Draft 或 Released等)、撰寫者、審查者、核定者等資訊,甚至文件的編號,如果有導入 ISO 文管制度或 CMMI,可依其格式辦理;不過老實說,人數規模沒有大到那種程度,做這些反而累死自己。所幸,審計查核重點並不在文件的格式或製作方式,主要是看 ERP 系統的增修,是否有相關的文件可以參考與傳承。

接下來應該有 Change Log(文件修訂記錄),記錄修訂日期、版本與修改內容。這些都是很好的追蹤記錄與管理方式(如果有文管系統則更理想)。

文件的目的、摘要,說明本文件的用途,內容的部份依實際需要撰寫即可,畢竟資訊單位不是軟體公司承接專案,需依軟體/專案開發所需文件格式撰寫。如果真要參考範本,像以前資策會出的 SDG 2.0(看到這個名詞就可以知道我的年代久遠...落寞),經濟部的軟體技術文件指引,都有很完整的規範與範例可以參考。

關於 SDG 2.0 的始末可以參考這一篇:即將走出人們視野外的 SDG 2.0

相關政府出版的技術文件要點

全系列文章列表


上一篇
[IT上櫃心法]-8.資料修改申請單
下一篇
[IT上櫃心法]-10.應用系統之使用者清單
系列文
IT上櫃心法31
0
海綿寶寶
iT邦大神 1 級 ‧ 2010-10-10 12:09:12

寫文件比不寫文件要難
而比寫文件要難的
就是更新文件了

老外最愛寫文件,強調文件的重要性
我們最恨寫文件,寫文件既煩又沒用

有沒有兩全其美的方法?
我唯一能想到的最佳解決方案
就是"文件自動產生器"
最好的例子就是像JavaDoc的機制
可以先宣告各function的IPO定義當成規格
然後寫程式
如果之後有修改程式
只要修改宣告部份的Tag
就可以按一個鍵產生程式文件
不但文件內容與程式內容相符合
程式員也不必重覆花時間寫文件

jamesjan iT邦高手 1 級 ‧ 2010-10-11 09:11:39 檢舉

有一部分如程式說明文件用這種方式產生就很適合,尤其是政府的專案很喜歡叫人家提供這種文件
但是,他們又不寫程式,也不知道產生這種文件對他們有什麼幫助,對開發廠商比較有幫助才對

idoncys iT邦新手 3 級 ‧ 2010-10-11 10:01:32 檢舉

把程式碼與商業邏輯寫好後都存到資料庫,系統執行時再到資料庫撈程式碼去演譯,這樣程式碼與商業邏輯的管理就可透過資料庫來進行,除此以外,架構圖與流程圖也一併存到資料庫,這樣包含程式碼與商業邏輯都可以透過圖來管理,並且直接線上驗證系統,會很方便.

0
pantc328
iT邦研究生 1 級 ‧ 2010-10-11 09:00:39

寫文件,我最討厭寫文件了.
為了寫文件而文件?
坦白說,你要什麼文件我都可以做給你.

以我程設師的觀點.
修了文件改Code.
修了Code改文件.
到最後Code跟文件根本是二馬子的事.

有時文件很簡單,但寫成Code很複雜.這我認了.
有時Code很簡單,但換成文件就很複雜.有時不只是文字還要畫架構圖,有時要寫學術論文..
寫Code30分,寫文件花3小時,什麼跟什麼?

坦白說寫Code不一定寫文件.
Code寫的好.名稱寫的好,流程有順序,一看就懂.
但台灣人英文就是差.名字取A1,A2,A3....然後寫一推註解這個變數在做什麼.

我以前接手一個中興大學畢業的碩士寫的資料庫.裡面有一個欄位叫做Big2.我怎麼看都看不懂又沒文件可以看.我叫他補文件.原來是大哥大的號碼!
然到你不會取CellPhone,MobilePhone,PhoneNumber??????這樣你不寫文件我都看的懂.

idoncys iT邦新手 3 級 ‧ 2010-10-11 09:48:28 檢舉

可以感覺您很不喜歡寫文件,大概習慣從code就可看到設計流程或原意.

但角色不同或許立場也會不同,以前要求設計師下班前寫日誌,貼在後勤論壇,包含事件主旨原委,處理概念,最後再貼上程式碼.為甚麼?因為他做了甚麼,是否聽懂交辦的事情,可從論述去了解,再從其預下的SQL指令,程式主體去看,是否作對做錯,可以在事前就作比較有效的稽核.

少了文件紀錄,為了解決事情,一樣是要花時間去問他將程式碼放在哪一段,再看其程式碼,工作量也是差不多,但程式碼沒有整件事情概觀,一件事情可能有多筆相關程式碼,要從事件需求去管理分散的相關程式碼,除非也作紀錄,不然要反推也不容易,而看的可能又是比較資深而成本高的人,這樣反而工作成本比較多.

而最重要的是,多年後客戶需求變更需要維護時,可能人事已非,如果不巧該事很複雜,要依靠當初主事的程設師,是否也要其離職後接電話回答相關疑問?而他是否有那個義務回答就是個風險,而新人要接手,又要從一堆散亂的程式檔中去翻找,找出來以後,還要再對事情原委解說與交辦一次,僅就系統成本與效率的考量,這樣的作法都不是很恰當.如果當初有處理事件的文件,可追蹤參考,可延續紀錄,對於客戶的後勤與新人的交接,都可以省下不少工作成本.

寫Code30分,寫文件花3小時,對我而言,這不是什麼跟什麼,而是一件蠻重要的事.

pantc328 iT邦研究生 1 級 ‧ 2010-10-11 10:13:57 檢舉

文件很重要是沒錯,但~
已我這幾年的IT觀察.
IT的速度越來越快.
一個Case,一個客戶,一個職員,一間公司,那麼多年,真的是不簡單.
在台灣,老闆炒短線,員工炒短線.
老闆將員工當什麼使用?用完了就丟,員工看不到未來.
員工也是打帶跑的心態,有什麼老闆就有什麼員工.

一個客戶要能維護那麼多年,這份情感真的.
就寫軟體,前一版的技術跟後一版的技術會非常的不同.就維護合約通常也是一年一簽.
如果說一個Case在多年後出問題要修改.要找到原系統文件也不簡單.通常需要在需求訪談或舊系統在Run過一遍後整個或部分系統重構.

//寫Code30分,寫文件花3小時,對我而言,這不是什麼跟什麼,而是一件蠻重要的事.
對你很重要,但就整個系統開發,你要考量時間跟成本.如果貴公司資源很多.跟中研院/中科院/工研院一樣,你就可以每天寫研究報告.

idoncys iT邦新手 3 級 ‧ 2010-10-11 11:30:36 檢舉

當老闆的好像都被您講的不是人了,我在猜,如果系統都是靠程式碼去堆積,當老闆的也只好拼命請程設師,然後年年不斷在產生程式碼,這些日積月累的程式碼終究會改變老闆作法,而開始一些短線的操作,當員工精疲力竭陷入程式碼堆,相對性也會猜面臨管理困境老闆可能出招,難免會想像有被無情丟棄的危機,這不就是一種惡性循環嗎?如果系統不是這樣,然後又很賺錢,或許就不會每個老闆都被您形容成這麼惡劣.

文件對於我而言主要的目的是要從中篩選整理出業務用文件,有機會讓未來的客戶線上看到系統的成形過程,是靠系統規劃與系統分析來建構的.為此我自己還在抽空寫我的 WEB 便利貼,希望能將一些分析結果貼在 WEB 上,讓系統的主體架構與細節處理都能夠呈現出來.

http://ithelp.ithome.com.tw/question/10039800

我們主要作商業資料庫應用專案,有些客戶維護合約已經超過10年了,還好在維護工作上也不是甚麼大問題,不過倒不是有文件的關係,而是我們的系統可用於所有不同類型的客戶,像進銷存與人事薪資,出口貿易等不同類型的產業或機關,系統有95%左右是一樣的,商業邏輯都存在客戶資料庫,然後動態在執行,所以專案大約都可控制在約3千列以內程式,其餘的都是資料庫定義好,版面排一排就可以了.新版的 WEB 甚至都將操作版面也一併存到客戶資料庫,以讓系統更輕巧,更方便整合管理.

因為系統很小,所以系統出問題的機率不高,幾乎都是在處理客戶新增的需求.所以雖然我沒有如工研院般的人力與資源,但面對所有新舊客戶的維護外,還是在想辦法不斷寫文件,目的之一也是希望有朝團隊成員增加時,能夠在不花太多時間成本上交接事情,並提供新進人員的工作參考.

我的後勤網雖然只有我一人在寫,但我還是會繼續寫,並邀請客戶也進來看,如果可以跟客戶形成互動,也算是溝通需求與討論問題的一種方法.

0
jamesjan
iT邦高手 1 級 ‧ 2010-10-11 09:21:09

以前做專案的時候,有兩份文件是審查的重點:使用手冊與操作手冊。

這兩個文件很容易混淆,一個是給使用者看的,一個是給維護單位看的。

就我以前的認知,給使用者看的是使用手冊,給維護人員看的是操作手冊。但是後來的經驗,好像這兩者被混在一起了。

給使用者看的文件,偏重功能的解說,與畫面的操作及畫面的欄位說明;給維護人員看的也會有前述的說明,但會搭配 Table Schema 及參數設定等說明文件。

做文件真的很累,以前在軟體公司就有專門製作文件的部門(而且是多國語言),使用 help 製作工具來做線上 help 文件(當時沒有深入去了解該部門的作業方式,所以知道的不多),研發人員根本不用去管這個東西。

但現在在MIS單位,說真的能省則省,文件大部分都存在每個需求申請單當中...這也是值得去改善的項目之一。

0
doesjudas
iT邦新手 2 級 ‧ 2010-10-11 09:50:38

只要是MIS, 沒人會喜歡寫文件.

通常寫文件只是備查, 實用性通常不高. 一來MIS角度寫的, USER不一定看的懂, 二來即時更新, 不容易做到. 這是文件經常遇到的狀況.

針對每個工作(也就是程式), 不妨提供MIS跟特定USER可以修改文件的功能, 初期MIS編寫基本描述, USER根據工作實務補充相關細節以及後續變更記錄, 這樣也許可以增加文件實用性.
PS: 基本操作跟工作流程圖, 因為修改狀況不多, 所以還是得MIS來編寫.

0
SunAllen
iT邦研究生 1 級 ‧ 2010-10-11 12:01:25

大大如果有寫文件的職缺,可以考慮小弟哦...

工作真難找Orz

0
Ken(Bigcandy)
iT邦大師 1 級 ‧ 2010-10-11 12:04:50

擔任MIS多年,資訊主管也多年,個人覺得,文件還是要做

如果不想做?
1.考慮人事、組織
2.依據上述條件,調整文件

例如,真的沒人,那就折衷一下,直接在程式碼裡面加上附註,只要讓另一個不相關的Programer看得懂即可。

IT人員異動難免,只能做好『備援』計畫。

我要留言

立即登入留言