[Year 12 Its] Prim vs Sec Data Sources & Docs

[Donna Benjamin]

On 23/05/2005, at 5:17 PM, Robert Timmer-Arends wrote:
> Wheeeee....... is anybody getting dizzy???
>
> Regards
> Robert T-A
> Brighton SC

Sorry!  Here's 2 more. But I'll stop forwarding them on to you now.

Steve Jenkin - member of the Australian Unix Users Group and
Brenda Aynsley - Chairman of the South Australian branch of the  
Australian Computer Society.

 From Steve Jenkin:

>> Perhaps our friends in industry can tell us if it is common
>> practice for the technical docs to be written by anyone other than
>> the programmer.
>>

A. There is a speciality of "technical writer".
    Most *good* documentation is created by a good tech writer.
    Almost all commercial documentation is created by tech writers.

B. The Unix/Open Source tradition is for the program creator(s) to write
a 'man' page.  The best pages are succinct, informative and complete -
and also mention the bugs, 'gotchas' and problems with the code.
The best Open Source projects have specific "Documentation Projects".

C. Programmers are chronically tardy & remiss when it comes to creating
documentation, even in-line comments, technical descriptions and design
notes...
The industry suffers from a plague of "no documentation". Y2K showed
even worse problems - like missing source code...

D. Writing documentation without reference to, or understanding of, the
source code, is writing a fantasy.  The prevalence of this practice
[writing what *should* or *could* be] is an on-going shame of the
industry.

E. "Documentation Decay", similar to "program bit-rot" is also endemic
in the industry.  You can't get hold of doco: for old versions, for
devices [like printers], for the current version of code, for the
Australian/local version of some global code....

----------------------------------
 From Brenda Aynsley:

gee whiz i cant accept that either are primary sources per se, but  
I'm more likely to accept an error log generated by a program/system  
as a primary source than technical documentation which for me is seen  
as:

a. a 'footnote' or comment to the (primary) source code contained in  
the codebase.
b. written as a specification/user guide/manual to explain the  
(primary) source code in which case its as likely to have been  
written by a tech writer as a programmer.

I am not sure that Industry cares per se whether you call them  
primary or secondary to be honest.  Perhaps the question has a  
context that we're not aware of but the students would be?


definitions :

Hairston and Ruszkiewicz define primary sources as the "materials on  
a topic upon which subsequent interpretations or studies are based,  
anything from first-hand documents such as poems, diaries, court  
records, and interviews to research results generated by experiments,  
surveys, ethnographies, and so on."

[hence my acceptance of an error log as a primary source]

"In contrast to primary sources, secondary sources are accounts  
written by people who were not at the scene.  Secondary sources are  
prepared based on the information contained in primary sources, and  
often explain or comment on the primary source material.  Let's look  
at the examples of primary sources we discussed above and see how  
they differ from secondary sources."

see http://www.bergen.cc.nj.us/Library/userguide/IV_A_prim_sec.html


cheers
brenda

-- 
Brenda Aynsley, FACS
Chairman ACS SA http://www.acs.org.au/





Donna Benjamin | donna at cc.com.au
Executive Director | Creative Contingencies
ph +61 3 93269985 | mob +61 418 310414
http://www.creativecontingencies.com