Software Documentation Jacques Carette Class: Communication Skills October 19, 2009 Jacques Carette (McMaster) Software Documentation October 19, 2009 1 / 20
Outline Introduction 1 Types 2 Focus on: Technical Documentation 3 Summary 4 Jacques Carette (McMaster) Software Documentation October 19, 2009 2 / 20
Introduction Definition Software documentation is written text that accompanies computer software. Jacques Carette (McMaster) Software Documentation October 19, 2009 3 / 20
Introduction Definition Software documentation is written text that accompanies computer software. Q: Is executable code documentation? Jacques Carette (McMaster) Software Documentation October 19, 2009 3 / 20
Introduction Definition Software documentation is written text that accompanies computer software. Q: Is executable code documentation? A: Yes, but it’s mostly meant for a computer. Jacques Carette (McMaster) Software Documentation October 19, 2009 3 / 20
Types Requirements - identify attributes, capabilities, characteristics, or qualities of a system. Foundation for what shall be or has been implemented. Architecture/Design - Overview of software. Includes environment and principles. Technical - Documentation of code, algorithms, interfaces and APIs, verification and testing results. End User - Manuals for end-users, administrators and support staff. Marketing - How to market product; market demand analysis. Jacques Carette (McMaster) Software Documentation October 19, 2009 4 / 20
Requirements Audience: customers, product managers, project managers, 1 sales, marketing, software architects, usability experts, interaction designers, developers, testers, ... Purpose: Inform all stakeholders of what software does / shall do. 2 Contents: Description of what software does / shall do! 3 Common errors: Including design (how it’s done), or hype 4 (marketing). Jacques Carette (McMaster) Software Documentation October 19, 2009 5 / 20
Architecture/Design Audience: software architects, designers and developers 1 Purpose: Communicate the “structure” of the software; 2 communicate the rationale behind various decisions. Contents: Explanations. Link the requirements to the actual code 3 structure and design. Key word: rationale, “reasons for”. Common errors: Too low-level (i.e. describes code) 4 Jacques Carette (McMaster) Software Documentation October 19, 2009 6 / 20
Technical Audience: designers and (internal and external) developers. 1 Purpose: Communicate the intended operation, and its current 2 status. Contents: A description of what every important aspect of a piece 3 of code is supposed to do, and why it works. This can be direct (comments) or indirect (tests). Common errors: It’s missing altogether. Documents the “code”. 4 Out of date. Jacques Carette (McMaster) Software Documentation October 19, 2009 7 / 20
User Audience: end users (diverse group!), administrators, support staff 1 Purpose: Describe the utility of each part of a system. 2 Contents: Can take different approaches: Tutorial, thematic (ex: 3 how-to and troubleshooting guides), reference (ex: man pages). Common errors: Marketing hype. Thinking that one-style-fits-all. 4 Jacques Carette (McMaster) Software Documentation October 19, 2009 8 / 20
Marketing Audience: Sales and Marketing 1 Purpose: Excite potential users about product; inform them of 2 what the product does; explain positioning with respect to competitors. Contents: ex: sales pitch. Clear, detailed information on utility. 3 Common errors: List of features. 4 Jacques Carette (McMaster) Software Documentation October 19, 2009 9 / 20
Breaking down technical documentation There really are 3 different kinds of technical documentation: code and algorithms (internal contract) 1 API and interface (external contract) 2 testing and verification results (contract verification) 3 Good contracts are formal. Any contract is better than no contract. Jacques Carette (McMaster) Software Documentation October 19, 2009 10 / 20
Internal contracts Purpose: document what code is supposed to do. Recommended method: tool-supported literate programming. Second-best: code comments which explain the intent of the code. Tools: noweb, nuweb, FunnelWeb are generic, some languages also support literate programming natively. (good examples make really really bad slides, but ...) Jacques Carette (McMaster) Software Documentation October 19, 2009 11 / 20
#include <ncurses.h>/*****************************************************/ int m[256 ] [ 256 ],a ,b ;;; ;;; WINDOW*w; char*l="" "\176qxl" "q" "q" "k" "w\ xm" "x" "t" "j" "v" "u" "n" ,Q[ ]= "Z" "pt!ftd‘" "qdc!‘eu" "dq!$c!nnwf"/** */"t\040\t";c( *** int u , int v){ v?m [u] [v- 1] |=2,m[u][v-1] & 48?W][v-1 ] & 15]]):0:0;u?m[u -1][v]|=1 ,m[ u- 1][ v]& 48? W-1 ][v ]& 15] ]):0:0;v< 255 ?m[ u][v+1]|=8,m[u][v+1]& 48? W][ v+1]&15]] ):0 :0; u < 255 ?m[ u+1 ][v ]|= 4,m[u+1][ v]&48?W+1][v]&15]]):0:0;W][ v]& 15] ]);}cu(char*q){ return *q ?cu (q+ 1)& 1?q [0] ++: q[0 ]-- :1; }d( int u , int/**/v, int/**/x, int y){ int Y=y -v, X=x -u; int S,s ;Y< 0?Y =-Y ,s, s=- 1:( s=1);X<0?X=-X,S =-1 :(S= 1); Y<<= 1;X<<=1; if(X>Y){ int f=Y -(X >>1 );; while(u!= x){ f>= 0?v+=s,f-=X:0;u +=S ;f+= Y;m[u][v]|=32;mvwaddch(w,v ,u, m[u ][ v]& 64? 60: 46) ;if (m[ u][ v]&16){c(u,v);; ;;; ;;; return;}} }else{int f=X -(Y>>1);; while (v !=y ){f >=0 ?u +=S, f-= Y:0 ;v +=s ;f+=X;m[u][v]|= 32;mvwaddch(w,v ,u,m[u][v]&64?60:46);if(m[u ][ v]& 16) {c( u,v ); ; return;;;}}}}Z( int/**/a, int b){ }e( int/**/y,int/**/ x){ int i ; for (i= a;i <=a +S;i++)d(y,x,i,b),d(y,x,i,b+L);for(i=b;i<=b+L;i++)d(y,x,a,i),d(y,x,a+ S,i ); ;;; ;;; ;;; ;;; ; mvwaddch(w,x,y,64); ;;; ;;; ;;; prefresh( w,b,a,0,0 ,L- 1,S-1 );} main( int V , char *C[ ] ){FILE*f= fopen(V==1?"prog.c"/******/ :C[ 1],"r");int/**/x,y,c, v=0 ;;; initscr (); Z(Z (raw () ,Z( curs_set(0),Z(1 ,noecho()))),keypad( stdscr,TRUE));w =newpad ( 300, 300 ) ; for (x= 255 ; x >=0 ;x-- ) for (y= 255 ;y>=0;y-- )m[ x][ y]= 0;x=y=0;refresh( );while ( (c= fgetc (f) )+1) {if( 0||c==10|| x== 256){x=0;y++;if(y==256 )break;;} else{m[x][y]=(c == ’~’ ?64 : c ==32 ?0: 16) ;;x ++; }}for(x=0 ;x< 256;x++)m [x][0]=16 ,m[ x][ 255]=16;for(y=0 Jacques Carette (McMaster) Software Documentation October 19, 2009 13 / 20 ;y< 256 ; y ++) m[0 ][y ] = 16,
X=1024; Y=768; A=3; J=0;K=-10;L=-7;M=1296;N=36;O=255;P=9;_=1<<15;E;S;C;D;F(b){E="1""111886:6:??AAF" "FHHMMOO55557799@@>>>BBBGGIIKK"[b]-64;C="C@=::C@@==@=:C@=:C@=:C5""31/513/5131/" "31/531/53"[b ]-64;S=b<22?9:0;D=2;}I(x,Y,X){Y?(X^=Y,X*X>x?(X^=Y):0, I (x,Y/2,X )):(E=X); }H(x){I(x, _,0);}p;q( c,x,y,z,k,l,m,a, b){F(c );x-=E*M ;y-=S*M ;z-=C*M ;b=x* x/M+ y*y/M+z *z/M-D*D *M;a=-x *k/M -y*l/M-z *m/M; p=((b=a*a/M- b)>=0?(I (b*M,_ ,0),b =E, a+(a>b ?-b:b)): -1.0);}Z;W;o (c,x,y, z,k,l, m,a){Z=! c? -1:Z;c <44?(q(c,x ,y,z,k, l,m,0,0 ),(p> 0&&c!= a&& (p<W ||Z<0) )?(W= p,Z=c): 0,o(c+ 1, x,y,z, k,l, m,a)):0 ;}Q;T; U;u;v;w ;n(e,f,g, h,i,j,d,a, b,V){o(0 ,e,f,g,h,i,j,a);d>0 &&Z>=0? (e+=h*W/M,f+=i*W/M,g+=j*W/M,F(Z),u=e-E*M,v=f-S*M,w=g-C*M,b=(-2*u-2*v+w) /3,H(u*u+v*v+w*w),b/=D,b*=b,b*=200,b/=(M*M),V=Z,E!=0?(u=-u*M/E,v=-v*M/E,w=-w*M/ E):0,E=(h*u+i*v+j*w)/M,h-=u*E/(M/2),i-=v*E/(M/2),j-=w*E/(M/2),n(e,f,g,h,i,j,d-1 ,Z,0,0),Q/=2,T/=2, U/=2,V=V<22?7: (V<30?1:(V<38?2:(V<44?4:(V==44?6:3)))) ,Q+=V&1?b:0,T +=V&2?b :0,U+=V &4?b:0) :(d==P?(g+=2 ,j=g>0?g/8:g/ 20):0,j >0?(U= j *j/M,Q =255- 250*U/M,T=255 -150*U/M,U=255 -100 *U/M):(U =j*j /M,U<M /5?(Q=255-210*U /M,T=255-435*U /M,U=255 -720* U/M):(U -=M/5,Q=213-110*U /M,T=168-113*U / M,U=111 -85*U/M) ),d!=P?(Q/=2,T/=2 ,U/=2):0);Q=Q< 0?0: Q>O? O: Q;T=T<0? 0:T>O?O:T;U=U<0?0: U>O?O:U;}R;G;B ;t(x,y ,a, b){n(M*J+M *40*(A*x +a)/X/A-M*20,M*K,M *L-M*30*(A*y+b)/Y/A+M*15,0,M,0,P, -1,0,0);R+=Q ;G+=T;B +=U;++a<A?t(x,y,a, b):(++b<A?t(x,y,0,b):0);}r(x,y){R=G=B=0;t(x,y,0,0);x<X?(printf("%c%c%c",R/A/A,G /A/A,B/A/A),r(x+1,y)):0;}s(y){r(0,--y?s(y),y:y);}main(){printf("P6\n%i %i\n255" "\n",X,Y);s(Y);} Jacques Carette (McMaster) Software Documentation October 19, 2009 15 / 20
#define a /* #<?php echo "\010Hello, world!\n";// 2> /dev/null > /dev/null \ ; // 2> /dev/null; x=a; $x=5; // 2> /dev/null \ ; if (($x)) // 2> /dev/null; then return 0; // 2> /dev/null; fi #define e ?> #define b */ #include <stdio.h> #define main() int main() #define printf printf( #define true ) #define function function main() { printf "Hello, world!\n"true/* 2> /dev/null | grep -v true*/; return 0; } #define c /* main #*/ Jacques Carette (McMaster) Software Documentation October 19, 2009 17 / 20
Recommend
More recommend
