Documentation. - Program Spec: My ugly way and why do I make it.

Non of programmer likes documentation over actual programming. I haven't seen one yet. But he/she should have ability to create one in easy to read format. When things so complicated, or need detailed detailed confirmation from power user group. You need to some way to share current status of system. Like 10 year old program got some requirement from user. MS visio is a good tool, but often times, user and developer himself doesn't have a copy of it. So I prefer use Powerpointer. Specs one goad is sharing, sometimes you have to show in projector.
Below is very little part of program and very part of drawing of spec.
Text format documentation is good way. Some time drawing reduces words.

This Pro*C program sample : Of cause , I had to change wording.

/* 3/29   OOW :  Oh Oo Wow  you don't need know what is this. It just trying to show part of source code*/

if (0 == strcmp((char *)o_iwow ,"OOW")){

MemSet( ls_tmp );

EXEC SQL

SELECT 'Y' into :ls_tmp

FROM T_MODEL_CHECK_TBL

WHERE model = :i_model

and chk_type = 'OWRJT';

if (SQLCODE != NOTFOUND && SQLCODE != SQLOK ) {

snprintf((char *)o_Msg , 100, "ERR:OWRJT check [%s][%s]", (char *)i_serial_no , i_model );

ret_code = 2;

goto LB_CUSTERROR;

}

if (0 == strcmp((char *)ls_tmp ,"Y")){

snprintf((char *)o_Msg , 100, "[OWRJT]OW Receive as reject phone[%s]", (char *)i_model );

ret_code = 2;

goto LB_CUSTERROR;

}

}

/* Certain Customer */

if (0 == strcmp((char *)i_customer , "xxxx")) {

MemSet(o_err ); MemSet(o_err1 );

EXEC SQL

SELECT CASE WHEN (TRUNC(sysdate) - TRUNC( repr_ship_date ) <= 90) THEN 'Y' ELSE 'N' END in_90, CASE WHEN repr_ship_date is null THEN 'NEW' WHEN (TRUNC(sysdate) - TRUNC( repr_ship_date ) >= 16)

THEN 'Y' ELSE 'N' END ov_30

INTO :o_err , :o_err1

FROM T_TRANSACTION_MASTER

WHERE serial_key =:i_serial_no ;

if ( SQLOK != SQLCODE ) {

faile_log(CRITICAL, "[%s]: NO 3rd Strike failed!:[%d][%s]\n",SERVICE_NAME,SQLCODE,SQLMSG);

ret_code = -1;

goto LB_DMLERROR;}

/* 30 day block: Not receive for */

if ( (0 == strcmp((char *)o_err1 , "N" ))&&

( 0 != strcmp((char *)i_reason , "973")) &&

( 0 != strcmp((char *)i_reason , "975")) ){

snprintf((char *)o_Msg , 100, "Returned in 30 days. Would you receive as reject phone?");

ret_code = 2;

goto LB_CUSTERROR;

}

}

LB_CUSTERROR :

SENDVALUE( ret_code , 0);

SENDVALUE( o_Msg , 0);

EXEC SQL ROLLBACK WORK;

faile_log(NORMAL, "[%s]: The SERVICE is terminated with Erro message--\n",SRC_NAME);

exit_system( );

As you can see, above long ugly coding can be shown user now. Even though it's still ugly, it became readable.
This much detailed discussion doesn't happen often. But when I have logic critical process and user never / won't keep their documentation, I do keep some written like this get sign off.