[an error occurred while processing this directive]

FIT2043 Technical documentation for software engineers - Semester 1 , 2008

Unit leader :

Kevin Korb

Lecturer(s) :

Clayton

  • Kevin Korb

Tutors(s) :

Clayton

  • Owen Woodbery
  • Joel Reicher

Introduction

Unit synopsis

This subject introduces technical writing in the context of software engineering. Fundamental concepts of good writing are introduced, including grammar, style, organization.  Other topics include: methods of developing documentation which integrate the process into the software engineering context (literate programming, agile methods, collaborative techniques); varieties of documentation and their purposes; argument and audience analysis; the effective use of graphics; type setting, markup and web publications.  Appropriate tools for 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' 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

1. An appropriate textbook has been selected.

2. The lectures are being completely redone, in part to incorporate more visual examples.

3. Lab assignments are being redone, both to incorporate groupwork and to provide more time (2 weeks) for students to complete them. Also, at least some assignment work will be reused in subsequent assignments, allowing marking feedback to be taken advantage of.

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) :

Joel Reicher
Owen Woodbery

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; Research  
3 Argument analysis: basics, rhetoric  
4 Publishing: layout, design, type setting  
Mid semester break
5 Agile document engineering: process, reviews, groupwork  
6 Documents: requirements, external design, user manual  
7 Argument analysis: advanced issues  
8 Graphics, visual rhetoric  
9 Documents: internal design, test plans  
10 Web publishing  
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. An account with google is recommended for groupwork.

    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 Blackboard, 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 MUSO (Monash University Studies Online). Blackboard is the primary application used to deliver your unit resources. Some units will be piloted in Moodle.

    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

    If your unit is piloted in Moodle, you will see a link from your Blackboard unit to Moodle at http://moodle.med.monash.edu.au.
    From the Faculty of Information Technology category, click on the link for your unit.

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

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