[Year 12 Its] Internal documentation

[Kevork Krozian]

Hi folks,

 Just thumbing through the Study Design Glossary p82 - 84

Internal documentation : " Comments written into program code to explain variables, procedures, methods. Well documented code assists future programmers to update the program".

External documentation: " Instructions for technical operators and end-users of software. Technical documentation includes: specifications and capabilities of the equipment, instructions about how to maintain and update software functions, disaster recovery, and a troubleshooting guide. End-user documentation may include a training manual and /or tutorial, quick help guide, "how to" manual, troubleshooting guide.  The instructions may be in one or a combination of forms such as hard copy  printed material, computer tutorials, on-screen help screens, Internet links to help sites. See also System Support Documentation.

  Based on the Study Design definitions , the Help screens would be external documentation John. 
Hope this helps.

Best Wishes
Kevork


>>> timmer at melbpc.org.au 05/19/05 07:57pm >>>
I agree with Barry and Allan. Just becuase 'help' can come as part of the
software package does not make it internal documentation. Traditionally,
internal documentation has meant that documentation that is embedded with
the code (comments, descriptive names, use of indentation...) and is
intended to help in the maintenance of the program, not its use. I guess it
has become a bit blurred with 'programmable' application software such as
spreadsheets and dbs but I think the principle still stands: internal
documentation is there to help in the maintenance of the 'solution', not in
its use.

Regards
Robert T-A
Brighton SC


----- Original Message -----
From: "john edwards" <john.edwards at gippslandgs.vic.edu.au>
To: <is at edulists.com.au>
Sent: Thursday, May 19, 2005 2:42 PM
Subject: [Year 12 Its] Internal documentation


> Hi All,
>
> I have a quick question regarding documentation.
>
> I have told my class that internal documentation consists of comments
within the coding and the documenting of variables and the like so that
their names form documentation (extrinsic and intrinsic).
>
> My question is whether, Help that comes with a software package like Word
or Excel, is considered internal or external. The Help itself must form part
of the software so does that mean it is internal or since it is available
only at run time is it considered external?
>
> Any assistance would be appreciated.
>
> Cheers,
>
> John Edwards
> Gippsland Grammar School
> Sale
>
> _______________________________________________
> http://www.edulists.com.au 
> IT Systems Mailing List kindly supported by
> http://www.vcaa.vic.edu.au - Victorian Curriculum and Assessment Authority
and
> http://www.vitta.org.au  - VITTA Victorian Information Technology Teachers
Association Inc

_______________________________________________
http://www.edulists.com.au 
IT Systems Mailing List kindly supported by
http://www.vcaa.vic.edu.au - Victorian Curriculum and Assessment Authority and
http://www.vitta.org.au  - VITTA Victorian Information Technology Teachers Association Inc