[Year 12 Its] Re: Internal documentation
Charmaine Taylor
tigeroz at alphalink.com.au
Sun May 22 22:26:30 EST 2005
Hi all,
There appear to be some problems with understandings of the meanings of
words being used in both the threads running on primary v secondary data
and internal v external documentation.
Rob's use of the terms primary and secondary seem to be in terms of use
ie the farmer's purpose in using the weather chart is primary as it is
his/her livelihood but for the beach trip this is of secondary
importance to the family. However, the distinction between the
classifications relates to the actual data itself rather than its
purpose . The chart is a primary source as it is a record of logged data
at a particular point in time and is presented as recorded. It hasn't
been interpreted or re-worked from the original.
Some comments have assumed internal documentation is that which is
embedded in the program or application ie on buttons and external is
that documentation which comes separately. However, I agree with Robert
T that internal has the meaning of being "for use within the
program/application" ie in maintaining the structure, integrity, or
updating the structure, perhaps variables (depending on how the program
is designed) of the program/application. External documentation is
that which is written for users of the program/application. Of course,
there are two types of external documentation - technical documentation
which is meant for those who maintain systems eg Network administrators,
repairers and end-user documentation - instructions for how to use the
program/application to produce the information required.
Cheers,
Charmaine Taylor
Sunbury Downs College
robertw wrote:
> Hi folks, sorry to drop in at this late stage, but the interpretation
> of primary and secondary data I put to my students, was that the data
> had to be first interpretted as having a purpose to aid decision
> making. In other words primary data was collected data that was not in
> a form that aided the decision makers directly, but after being
> processed in a certain way, and could then be called secondary data,
> it is was in state to aid decision making.
> Hence what might be primary data to some people, could be secondary to
> to others.
> For example the synoptic weather chart in the newspaper may be
> secondary data to a family deciding whether to go the beach tomorrow,
> but for a farmer deciding on when to plant crops, the same chart may
> be considered primary data, as many of them may need to be collected
> and processed before the farmer can decide what to do.
> So unless the primary and secondary notion is placed in a context that
> makes these distinctions clearly apparent then no end of confusion
> will result.
> Cheers,
> Rob Ward
> ICT and Electronics
> Curriculum Coordinator
> Lakes Entrance Secondary College
> Kevork Krozian writes:
>
>> Hi Robert,
>> Regrettably no such definitions exist for primary and secondary data
>> and should be added for future reference as the logical conclusion to
>> our rather long thread !!
>> Kevork Krozian
>> Mailing List Creator and Administrator
>> kevork at edulists.com.au
>> www.edulists.com.au
>> Tel: 0419 356 034
>> ----- Original Message ----- From: "Robert Timmer-Arends"
>> <timmer at melbpc.org.au>
>> To: "Year 12 Information Technology Systems Teachers' Mailing List"
>> <is at edulists.com.au>
>> Sent: Friday, May 20, 2005 6:30 PM
>> Subject: Re: [Year 12 Its] Internal documentation
>>
>>> 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
>>> _______________________________________________
>>> 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
>
> .
>
More information about the is
mailing list