FIT2043 Technical documentation for software engineers - Semester 2 , 2007

Unit leader :

Kevin Korb

Lecturer(s) :

Clayton

  • Kevin Korb

Tutors(s) :

Clayton

  • Owen Woodbery

Introduction

Unit synopsis

Problems with paper-based and on-line documentation; types of technical documentation used in software engineering; document specifications; minimalist design philosophy; graphic design of technical documentation; the context of technical writing; the writing process (analysis, planning, generation, testing, revision and maintenance of written texts); document publication techniques (including SGML, LaTeX and XML); the role of hypertext, hypermedia and markup languages in technical documentation; small-volume and large-volume hypertext; collaborative hypertext; intelligent hypertext.

Learning outcomes

Knowledge and Understanding

At the completion of this unit, students will have an understanding of:

K1. Be able to organise and write clear technical documentation.

K2. Understand the different types and roles of technical documentation, including code documentation (literate programming methods, function header documentation), internal designs, external designs, reference manuals, guides and introductory manuals.

K3. Understand the use of the basic types of tools for producing documentation: editors, text formatters, typesetters, desktop publishers, graphics tools, printing and viewing tools.

K4. Understand the role of style in writing.

K5. Understand different approaches to the writing process and which approach best suits the individual student.

Attitudes, Values and Beliefs

At the completion of this unit, students will have attitudes that will allow them to:

A1. Be sensitive to the aims and uses of effective technical documentation at all stages in a project.

A2. Be aware of different writing methods and styles and their suitability to different tasks.

A3. Appreciate the wider use of documentation in evaluating, promoting, and supporting projects.

A4. Develop a sensitivity to different reader / audience types.

Practical Skills

At the completion of this unit, students will be able to:

P1. Be able to write effective and clear documentation.

P2. Be able to use one of each major kind of documentation development and delivery tool.

Workload

2 hr lecture, 2 hr practical lab, 8 hrs of study per week.

Unit relationships

Prerequisites

Before attempting this unit you must have satisfactorily completed FIT1002 or equivalent introductory programming unit (e.g. CPE1001, CSE1202, GCO1811, MMS1801, MMS1802).

Relationships

FIT2043 is a core unit in the BSE degree. It is also required for the IBL program in BCS.

You may not study this unit and any of CSC1040, CSE1305, CSE1402, SFT2203, SYS2204 without specific approval.

Continuous improvement

Monash is committed to ‘Excellence in education' and strives for the highest possible quality in teaching and learning. To monitor how successful we are in providing quality teaching and learning Monash regularly seeks feedback from students, employers and staff. Two of the formal ways that you are invited to provide feedback are through Unit Evaluations and through Monquest Teaching Evaluations.

One of the key formal ways students have to provide feedback is through Unit Evaluation Surveys. It is Monash policy for every unit offered to be evaluated each year. Students are strongly encouraged to complete the surveys as they are an important avenue for students to "have their say". The feedback is anonymous and provides the Faculty with evidence of aspects that students are satisfied and areas for improvement.

Student Evaluations

The Faculty of IT administers the Unit Evaluation surveys online through the my.monash portal, although for some smaller classes there may be alternative evaluations conducted in class.

If you wish to view how previous students rated this unit, please go to http://www.monash.edu.au/unit-evaluation-reports/

Over the past few years the Faculty of Information Technology has made a number of improvements to its courses as a result of unit evaluation feedback. Some of these include systematic analysis and planning of unit improvements, and consistent assignment return guidelines.

Monquest Teaching Evaluation surveys may be used by some of your academic staff this semester. They are administered by the Centre for Higher Education Quality (CHEQ) and may be completed in class with a facilitator or on-line through the my.monash portal. The data provided to lecturers is completely anonymous. Monquest surveys provide academic staff with evidence of the effectiveness of their teaching and identify areas for improvement. Individual Monquest reports are confidential, however, you can see the summary results of Monquest evaluations for 2006 at http://www.adm.monash.edu.au/cheq/evaluations/monquest/profiles/index.html

Improvements to this unit

This is a new subject.

Unit staff - contact details

Unit leader

Dr Kevin Korb
Reader
Phone +61 3 990 55198
Fax +61 3 990 55157

Lecturer(s) :

Dr Kevin Korb
Reader
Phone +61 3 990 55198
Fax +61 3 990 55157

Tutor(s) :

Failed to retrieve details for Owen Woodbery

Teaching and learning method

2 lectures per week, one dedicated to document structure, writing technique, document types and related issues of content, audience analysis and document aims. One lecture per week dedicated to electronic publishing tools and technique, covering revision control, markup languages, literate programming, general tools issues, and graphics formats usage.

One prac per week which aims to reinforce theory with direct application. Students are required to practice the theoretical content covered in lectures. Homework prep from pracs often includes online research on topics covered in theory.

Tutorial allocation

Allocate+ is used to register for labs.

Communication, participation and feedback

Monash aims to provide a learning environment in which students receive a range of ongoing feedback throughout their studies. You will receive feedback on your work and progress in this unit. This may take the form of group feedback, individual feedback, peer feedback, self-comparison, verbal and written feedback, discussions (on line and in class) as well as more formal feedback related to assignment marks and grades. You are encouraged to draw on a variety of feedback to enhance your learning.

It is essential that you take action immediately if you realise that you have a problem that is affecting your study. Semesters are short, so we can help you best if you let us know as soon as problems arise. Regardless of whether the problem is related directly to your progress in the unit, if it is likely to interfere with your progress you should discuss it with your lecturer or a Community Service counsellor as soon as possible.

Unit Schedule

Week Topic Key dates
1 English  
2 English style  
3 Revision management  
4 Latex  
5 Writing technique  
6 Latex  
7 External design  
8 Internal design  
9 Test plans  
10 Graphics  
Mid semester break
11 User manuals  
12 Literate Programming  
13 Revision + Prac Exam  

Unit Resources

Prescribed text(s) and readings

Prescribed texts:

  • Woolever, K.R., Writing for the Technical Professions, Longman, 1999.

    • Recommended text(s) and readings

    Recommended texts:
  • William Murdick (2003) Portable Technical Writer. Houghton Mifflin
  • Thomas T. Barker (2003) Writing Software Documentation: A Task-Oriented Approach. Longman.
  • Goosens M. Rahtz S., The Latex Web Companion, Addison-Wesley, 1999.
  • Mittelbach F. Goosens M. , The Latex Companion, Addison-Wesley,  (1st or 2nd Ed).
  • Kopka H. Daly P.W., A Guide to Latex, Addison-Wesley, 1993.
  • William Knowlton Zinsser (2001) On Writing Well: The Classic Guide to Writing Non-Fiction. Quill Press
  • George Orwell (2003) Politics and the English Language, in Shooting an Elephant: And Other Essays. Penguin Books Ltd.

    • Study resources

    Study resources we will provide for your study are:

    • Weekly detailed lecture notes;
    • Weekly laboratory tasks and assignments with sample solutions provided one to two weeks later;
    • A sample examination and suggested solution;
    • Discussion groups;
    • This Unit Guide outlining the administrative information for the unit;
    • The unit web site on MUSO, where resources outlined above will be made available.

    Library access

    The Monash University Library site contains details about borrowing rights and catalogue searching. To learn more about the library and the various resources available, please go to http://www.lib.monash.edu.au.  Be sure to obtain a copy of the Library Guide, and if necessary, the instructions for remote access from the library website.

    Monash University Studies Online (MUSO)

    All unit and lecture materials are available through the MUSO (Monash University Studies Online) site. You can access this site by going to:

    1. a) https://muso.monash.edu.au or
    2. b) via the portal (http://my.monash.edu.au).

    Click on the Study and enrolment tab, then the MUSO hyperlink.

    In order for your MUSO unit(s) to function correctly, your computer needs to be correctly configured.

    For example :

    • MUSO supported browser
    • Supported Java runtime environment

    For more information, please visit

    http://www.monash.edu.au/muso/support/students/downloadables-student.html

    You can contact the MUSO Support by: Phone: (+61 3) 9903 1268

    For further contact information including operational hours, please visit

    http://www.monash.edu.au/muso/support/students/contact.html

    Further information can be obtained from the MUSO support site:

    http://www.monash.edu.au/muso/support/index.html

    Assessment

    Unit assessment policy

    50% practical labs; 50% lab exam

    Assignment tasks

    • Assignment Task
      Title :
      Assignments will be described as they are prepared during semester, in MUSO.
      Description :
      Weighting :
      Criteria for assessment :
      Due date :

    Examinations

    • Examination
      Weighting :
      50%
      Length :
      2 hours
      Type ( open/closed book ) :
      Open book

    Assignment submission

    Submitted via MUSO during practical labs.

    Assignment coversheets

    University and Faculty policy on assessment

    Due dates and extensions

    The due dates for the submission of assignments are given in the previous section. Please make every effort to submit work by the due dates. It is your responsibility to structure your study program around assignment deadlines, family, work and other commitments. Factors such as normal work pressures, vacations, etc. are seldom regarded as appropriate reasons for granting extensions. Students are advised to NOT assume that granting of an extension is a matter of course.

    To request an extension apply to the lecturer via email at least  one day prior to the lab in which the assignment is to be completed.

    Late assignment

    In general there will be no late assignments in this subject. Assignments are finalized during pracs. With approval of the tutor, you can switch labs. Otherwise, late assignments will be unmarked, receiving a 0, unless pre-approved by the lecturer or a relevant medical certificate is provided. 

    Return dates

    Students can expect assignments to be returned within two weeks of the submission date or after receipt, whichever is later.

    Assessment for the unit as a whole is in accordance with the provisions of the Monash University Education Policy at:

    http://www.policy.monash.edu/policy-bank/academic/education/assessment/

    We will aim to have assignment results made available to you within two weeks after assignment receipt.

    Plagiarism, cheating and collusion

    Plagiarism and cheating are regarded as very serious offences. In cases where cheating  has been confirmed, students have been severely penalised, from losing all marks for an assignment, to facing disciplinary action at the Faculty level. While we would wish that all our students adhere to sound ethical conduct and honesty, I will ask you to acquaint yourself with Student Rights and Responsibilities (http://www.infotech.monash.edu.au/about/committees-groups/facboard/policies/studrights.html) and the Faculty regulations that apply to students detected cheating as these will be applied in all detected cases.

    In this University, cheating means seeking to obtain an unfair advantage in any examination or any other written or practical work to be submitted or completed by a student for assessment. It includes the use, or attempted use, of any means to gain an unfair advantage for any assessable work in the unit, where the means is contrary to the instructions for such work. 

    When you submit an individual assessment item, such as a program, a report, an essay, assignment or other piece of work, under your name you are understood to be stating that this is your own work. If a submission is identical with, or similar to, someone else's work, an assumption of cheating may arise. If you are planning on working with another student, it is acceptable to undertake research together, and discuss problems, but it is not acceptable to jointly develop or share solutions unless this is specified by your lecturer. 

    Intentionally providing students with your solutions to assignments is classified as "assisting to cheat" and students who do this may be subject to disciplinary action. You should take reasonable care that your solution is not accidentally or deliberately obtained by other students. For example, do not leave copies of your work in progress on the hard drives of shared computers, and do not show your work to other students. If you believe this may have happened, please be sure to contact your lecturer as soon as possible.

    Cheating also includes taking into an examination any material contrary to the regulations, including any bilingual dictionary, whether or not with the intention of using it to obtain an advantage.

    Plagiarism involves the false representation of another person's ideas, or findings, as your own by either copying material or paraphrasing without citing sources. It is both professional and ethical to reference clearly the ideas and information that you have used from another writer. If the source is not identified, then you have plagiarised work of the other author. Plagiarism is a form of dishonesty that is insulting to the reader and grossly unfair to your student colleagues.

    Register of counselling about plagiarism

    The university requires faculties to keep a simple and confidential register to record counselling to students about plagiarism (e.g. warnings). The register is accessible to Associate Deans Teaching (or nominees) and, where requested, students concerned have access to their own details in the register. The register is to serve as a record of counselling about the nature of plagiarism, not as a record of allegations; and no provision of appeals in relation to the register is necessary or applicable.

    Non-discriminatory language

    The Faculty of Information Technology is committed to the use of non-discriminatory language in all forms of communication. Discriminatory language is that which refers in abusive terms to gender, race, age, sexual orientation, citizenship or nationality, ethnic or language background, physical or mental ability, or political or religious views, or which stereotypes groups in an adverse manner. This is not meant to preclude or inhibit legitimate academic debate on any issue; however, the language used in such debate should be non-discriminatory and sensitive to these matters. It is important to avoid the use of discriminatory language in your communications and written work. The most common form of discriminatory language in academic work tends to be in the area of gender inclusiveness. You are, therefore, requested to check for this and to ensure your work and communications are non-discriminatory in all respects.

    Students with disabilities

    Students with disabilities that may disadvantage them in assessment should seek advice from one of the following before completing assessment tasks and examinations:

    Deferred assessment and special consideration

    Deferred assessment (not to be confused with an extension for submission of an assignment) may be granted in cases of extenuating personal circumstances such as serious personal illness or bereavement. Special consideration in the awarding of grades is also possible in some circumstances. Information and forms for Special Consideration and deferred assessment applications are available at http://www.monash.edu.au/exams/special-consideration.html. Contact the Faculty's Student Services staff at your campus for further information and advice.