> 1.標題項目都要做說明,認證我們沒做也要寫清楚,不可以只是列一個標題,
>   這樣文件不完整
文件和實作可以分成兩個東西來看,但是是相關的
我的意思是說就如老師提到的
就算沒有 impl. 完成,也是要把文件的部分寫清楚
最多就是註明,這個部分未完成實作,但是文件要清楚的講你們的架構
(如果有實作部分,也是可以包含進去,就像軟工一樣
 ex: 你們的 message flow 就是比較偏 impl. 的東西

當初明彥和我做專題的時候,其實是花了大部分時間先做好文件
然後照著文件 impl.  最後才是把文件 refine 成論文和報告格式

> 2.系統架構圖,用到jxta哪邊都沒有寫,使用者看到也不知道我們如何去使用jxta
ref. 別人的東西,要清楚的說你用了別人的那部分,你和他怎麼整合
關係怎樣,而不是像報告上,兩張圖丟在那邊
甚至是建議你們討論好兩邊架構是怎樣整合,然後重畫過一張圖
印出來的報告是黑白的,所以可能可以用粗框去框出來區分

> 4.後面的每張圖片都沒有說明等於沒話,還有石頭你話那些系統循序圖跟使用者案例之類的
>   每張圖都被念,老師說至少要加說明....
這個部分以前我們也被批過
老師不會想看到每一段的標題下面,就是一張大大的圖
然後才說明,
而是要先一段概述,然後插圖,對圖說明解釋

不能是這樣:

    3   XX 系統架構

    3.1 yy 架構圖
        圖在這裡

        如上圖(如圖X)所示,blah blah

要是這樣:

    3   XX 系統架構
        本節 blah blah  (概述這一節的重點,長度自己抓,不需太多也不要太短)

    3.1 yy 架構圖
        這邊簡單的先描述一段,這邊想要說明什麼,然後適當的用連接詞,如圖 X
    所示,blah blah

        圖在這裡

        可以又一段文字來接下面,然後對圖做說明,.......
    圖中的元件說明如下:

        。 XXX
            description
        。 YYY
            description
        …
        …


> 5.實作階段規劃還有ㄧ些屬於開發細節的東西放到附錄(appendix)
> 6.流程圖標準化
> 7.流程圖說明
> 8.api詳細說明,參數描述(用java doc產出來在修吧..)
> 9.api or module之間關西描述,要讓使用者看到就知道怎摸用api,用jxta的service
>   知道我們的架構
> 10.api後面要接使用者範例,告訴使用者如何使用api
這邊你們可能要討論一下,然後看一下你們文件的定位
是屬於系統文件還是偏實作文件

ex:
    以前我們的作法:
        簡介、相關研究、系統架構、實作架構、API、結論、參考文獻

    另一種我直覺想到的則是
        簡介、相關研究、系統架構、結論、參考文獻、Appendix(impl. arch. and API,
        user guide for using APIs)




基本上你們接觸自己的架構是好幾個月的時間,可能 message flow, arch.
一看就很清楚
但是沒有說明的圖,對剛接觸你們文件的人
可能是一堆垃圾圖,通常也不會再去猜,最後文件丟掉...
所以試著以讓一個不知道你們系統架構的人,可以看懂你們的文件

老師談到的 self-content

pcjustin 發表在 痞客邦 PIXNET 留言(0) 人氣()