FIT2043 Technical documentation for software engineers - Semester 1, 2009

PDF unit guide

Download PDF version Download the unit guide in PDF

Unit leader :

Kevin Korb

Lecturer(s) :

Clayton

  • Kevin Korb

Tutors(s) :

Clayton

  • Robyn McNamara

Introduction

Welcome to FIT2043 Technical Documentation for Software Engineers. This is a core unit for BSE and a prerequisite for BCS students participating in IBL.

Unit synopsis

This subject introduces technical writing in the context of software
engineering. Fundamental concepts of software documentation are
introduced, including document types and their uses, document design
and review, user-centered design and audience analysis.  Other topics
include: literate programming, agile methods, collaborative
techniques; argument analysis; the effective use of graphics; type
setting, markup and web publications.  Appropriate tools for most of
these topics are introduced.

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’ (Monash Directions 2025 - http://www.monash.edu.au/about/monash-directions/directions.html) 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. One of the key formal ways students have to provide feedback is through Unit Evaluation Surveys. The University’s Unit Evaluation policy (http://www.policy.monash.edu/policy-bank/academic/education/quality/unit-evaluation-policy.html) requires that every unit offered is 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.

Faculties have the option of administering the Unit Evaluation survey online through the my.monash portal or in class. Lecturers will inform students of the method being used for this unit towards the end of the semester.

Student Evaluations

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

Improvements to this unit

1. After consultation with BSE lecturers, an assignment for developing a basic requirements specification, together with supporting lecture material, has been added.

2. The assignments have been revised to provide more guidance to students. Exemplars for assignments have been created for this purpose as well.

3. On-line support for 2043 has switched to Moodle.

Unit staff - contact details

Unit leader

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

Contact hours : Tue 3.00-4.00pm and Thr 12.00-1.00pm or by email appointment.

Lecturer(s) :

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

Tutor(s) :

Ms Robyn Mcnamara

Teaching and learning method

2 lectures per week, covering writing concepts and methods and the tools needed to develop and publish documents.

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; Grammar  
2 Style; Writing technique; Audience Analysis  
3 Presentations; Argument analysis  
4 Publishing: design, typesetting; Documents: requirements  
5 Agile document engineering: process, reviews, groupwork, user-centered design  
6 Documents: requirements, external design, user manual  
Mid semester break
7 Graphics, visual rhetoric  
8 Documents: internal designs  
9 Web publishing  
10 Documents: test plans  
11 Literate programming, comments, help text  
12 Other document types  
13 Revision + Prac Exam  

Unit Resources

Prescribed text(s) and readings

Prescribed texts:

  • S Dobrin, C Keller, C Weisser (2008). Technical Communication in the 21st Century, Prentice Hall.
  • Recommended text(s) and readings

    Recommended texts:
  • 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.
  • W Strunk & EB White (2000) Elements of Style. Longman.
  • HW Fowler, Modern English Usage. (Editions up to 1933, but not after.) 
  • 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.
  • Required software and/or hardware

    Software required will be available in the Linux labs, including: Latex, Firefox, emacs, bibtex, gv, dvips, xfig, RCS.

    Equipment and consumables required or provided

    You will need access to a Linux system and the internet.

    Study resources

    Study resources we will provide for your study are:

    • Weekly detailed lecture notes;
    • Bi-weekly laboratory assignments;
    • Sample documents;
    • A sample examination and suggested solution;
    • Discussion groups;
    • This Unit Guide outlining the administrative information for the unit;
    • The unit web site on Moodle, 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.

    The Educational Library and Media Resources (LMR) is also a very resourceful place to visit at http://www.education.monash.edu.au/library/

    Monash University Studies Online (MUSO)

    All unit and lecture materials are available through MUSO (Monash University Studies Online). Blackboard is the primary application used to deliver your unit resources. Some units will be piloted in Moodle. If your unit is piloted in Moodle, you will see a link from your Blackboard unit to Moodle (http://moodle.monash.edu.au) and can bookmark this link to access directly. In Moodle, from the Faculty of Information Technology category, click on the link for your unit.

    You can access MUSO and Blackboard via the portal: http://my.monash.edu.au

    Click on the Study and enrolment tab, then Blackboard under the MUSO learning systems.

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

    For example:

    • Blackboard 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% bi-weekly lab assignments; 50% lab exam. Hurdle requirements specify that to pass this unit, a student must obtain :

    • 40% or more in the unit's examination and
    • 40% or more in the unit's non-examination assessment
       and
    • an overall unit mark of 50% or more
    If a student does not achieve 40% or more in the unit examination or the unit non-examination assessment then a mark of no greater than 44-N will be recorded for the unit.

    Assignment tasks

    • Assignment Task

      Title : Assignments will be described as they are prepared during semester, in Moodle.

      Description :

      Weighting :

      Criteria for assessment :

      Due date :

    Examinations

    • Examination 1

      Weighting : 50%

      Length : 2 hours

      Type ( open/closed book ) : Open book

      Remarks ( optional - leave blank for none ) :

      Prac exam


    Assignment submission

    Submitted via Moodle.

    Assignment coversheets

    Coversheets will be available with the assignments in Moodle.

    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 should be 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. 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.