[Year 12 Its] Internal documentation

[Robert Timmer-Arends]

Well spotted Kevork

and a timely reminder that when it comes to definitions the study design
gloassary is the bible - assuming of course that the term is in it!

Regards
Robert T-A
Brighton SC

----- Original Message -----
From: "Kevork Krozian" <Kroset at novell1.fhc.vic.edu.au>
To: <is at edulists.com.au>
Sent: Friday, May 20, 2005 4:21 PM
Subject: Re: [Year 12 Its] Internal documentation


> 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
>
>
> _______________________________________________
> 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