Software Documentation Jacques Carette Class: Communication Skills - - PowerPoint PPT Presentation

Software Documentation

Jacques Carette

Class: Communication Skills

October 19, 2009

Jacques Carette (McMaster) Software Documentation October 19, 2009 1 / 20

Outline

1

Introduction

2

Types

3

Focus on: Technical Documentation

4

Summary

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

1

Audience: customers, product managers, project managers, sales, marketing, software architects, usability experts, interaction designers, developers, testers, ...

2

Purpose: Inform all stakeholders of what software does / shall do.

3

Contents: Description of what software does / shall do!

4

Common errors: Including design (how it’s done), or hype (marketing).

Jacques Carette (McMaster) Software Documentation October 19, 2009 5 / 20

Architecture/Design

1

Audience: software architects, designers and developers

2

Purpose: Communicate the “structure” of the software; communicate the rationale behind various decisions.

3

Contents: Explanations. Link the requirements to the actual code structure and design. Key word: rationale, “reasons for”.

4

Common errors: Too low-level (i.e. describes code)

Jacques Carette (McMaster) Software Documentation October 19, 2009 6 / 20

Technical

1

Audience: designers and (internal and external) developers.

2

Purpose: Communicate the intended operation, and its current status.

3

Contents: A description of what every important aspect of a piece

• f code is supposed to do, and why it works. This can be direct

(comments) or indirect (tests).

4

Common errors: It’s missing altogether. Documents the “code”. Out of date.

Jacques Carette (McMaster) Software Documentation October 19, 2009 7 / 20

User

1

Audience: end users (diverse group!), administrators, support staff

2

Purpose: Describe the utility of each part of a system.

3

Contents: Can take different approaches: Tutorial, thematic (ex: how-to and troubleshooting guides), reference (ex: man pages).

4

Common errors: Marketing hype. Thinking that one-style-fits-all.

Jacques Carette (McMaster) Software Documentation October 19, 2009 8 / 20

Marketing

1

Audience: Sales and Marketing

2

Purpose: Excite potential users about product; inform them of what the product does; explain positioning with respect to competitors.

3

Contents: ex: sales pitch. Clear, detailed information on utility.

4

Common errors: List of features.

Jacques Carette (McMaster) Software Documentation October 19, 2009 9 / 20

Breaking down technical documentation

There really are 3 different kinds of technical documentation:

1

code and algorithms (internal contract)

2

API and interface (external contract)

3

testing and verification results (contract verification) 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 ;y< 256 ; y ++) m[0 ][y ] = 16, Jacques Carette (McMaster) Software Documentation October 19, 2009 13 / 20

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

External contracts

Purpose: document the services some code/module/class/etc is

• ffering.

Recommended method: tool-supported embedded comments. Second-best: code comments which explain the interface. Tools: javadoc, doxygen, haddock, ocamldoc, ... (let’s go on the web)

Jacques Carette (McMaster) Software Documentation October 19, 2009 18 / 20

Contract Verification

Purpose: verify that (parts of) contracts are obeyed. Recommended method: tool-supported tests and proofs. Second-best: code reviews. Not recommended: hand testing, hand proofs. Tools: junit, QuickCheck, theorem provers.

Jacques Carette (McMaster) Software Documentation October 19, 2009 19 / 20

Summary

Documentation is written text which accompanies software. Differents kinds, different audiences.

Jacques Carette (McMaster) Software Documentation October 19, 2009 20 / 20