Re: OT : Writing Documentation

A quick and dirty answer from my background in program management.

Document what your current code does and how it does it so that in case it doesn't work someone else can easily find your mistake. If they want to add new functionality to your code, your documentation should guide them in how to do it without destroying the current functionality.

Document why you made the decisions that you did in your code so that when the technology changes the page(s) can be re-written in the new technology with the identical functionality.

Your 100 lines of code should produce about 2 pages of documentation. The code should also be self-documenting.

Good luck (though I see software development as a career step backwards for a DBA).

                                                                                       
               
                    "Michael"                                                          
               
                    <oqij4ngfcrweuh001_at_sneak        To:     Multiple recipients of 
list ORACLE-L      
                    email.com>                      <ORACLE-L_at_fatcity.com>             
               
                    Sent by:                        cc:                                
               
                    root_at_fatcity.com                Subject:     OT : Writing 
Documentation           
                                                                                       
               
                                                                                       
               
                    08/25/2001 11:45 PM                                                
               
                    Please respond to                                                  
               
                    ORACLE-L                                                           
               
                                                                                       
               
                                                                                       
               

Hi everybody,

     Sorry, I realise this is a bit off topic - but I need to ask a question of
all those developers out there.

     At the moment, the company I work for has a Web Developer position vacant
(working with ASP/ColdFusion with a SQL 7 Database Server).

     SQL 7 isn't exaclty oracle, I know, but it's a step in the direction that
I'd like to take (db development stuff). So please, don't flame me for that :)

     In order to ensure that the applicants aren't idiots we've been asked to do
a simple test which basically involves taking an access database with four tables inside it, and creating a login and product view page. I've done this, so this isn't related to my question (which I'll eventually get to)

     Additional to us having to submit the code to these pages, we are required
to submit documentation on how our pages work, and why we made it work that way. I am able to do this, sure, but I'm not entirely sure if my format will
be correct. So, can anybody out there give me some tips on what this documentatoin should contain? There's only about a 100 lines between the two
pages, so there isn't much to write about.

     Any information anybody can supply would be _greatly_ appreciated. I have
to hand this thing in in the not-to-distant future, so if you could rush it too I'd like that even more :)

     Thanks for your time, and once again, sorry for posting off-topic, but this
is the best place I could think to ask.

Cheers,
Michael.
v

--
Please see the official ORACLE-L FAQ: http://www.orafaq.com
--
Author: Michael
  INET: oqij4ngfcrweuh001_at_sneakemail.com

Fat City Network Services    -- (858) 538-5051  FAX: (858) 538-5051
San Diego, California        -- Public Internet access / Mailing Lists
--------------------------------------------------------------------
To REMOVE yourself from this mailing list, send an E-Mail message
to: ListGuru_at_fatcity.com (note EXACT spelling of 'ListGuru') and in
the message BODY, include a line containing: UNSUB ORACLE-L


(or the name of mailing list you want to be removed from).  You may

also send the HELP command for other information (like subscribing).


-- 
Please see the official ORACLE-L FAQ: http://www.orafaq.com
-- 
Author: 
  INET: tday6_at_csc.com

Fat City Network Services    -- (858) 538-5051  FAX: (858) 538-5051
San Diego, California        -- Public Internet access / Mailing Lists
--------------------------------------------------------------------
To REMOVE yourself from this mailing list, send an E-Mail message
to: ListGuru_at_fatcity.com (note EXACT spelling of 'ListGuru') and in
the message BODY, include a line containing: UNSUB ORACLE-L


(or the name of mailing list you want to be removed from).  You may

also send the HELP command for other information (like subscribing).