Skip to the content | Change text size
PDF unit guide

FIT2043 Technical documentation for software engineers - Semester 1, 2010

Chief Examiner:

Dr Sita Ramakrishnan
Senior Lecturer
Phone: +61 3 990 58689
Fax: +61 3 990 55159

Contact hours: Lecture Thurs - 3-5pm, CL25,S9, contact 1 hour before lecture

Lecturer(s) / Leader(s):

Clayton

Sita Ramakrishnan (Lecturer), Nizam Abdallah (Tutor)

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 unit covers 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

At the completion of this unit students will have -
A knowledge and understanding of:
  • how to organise and write clear technical documentation.
  • 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.
  • the use of the basic types of tools for producing documentation: editors, text formatters, typesetters, desktop publishers, graphics tools, printing and viewing tools.
  • the role of style in writing.
  • different approaches to the writing process and which approach best suits the individual student.
Developed attitudes that enable them to:
  • be sensitive to the aims and uses of effective technical documentation at all stages in a project.
  • be aware of different writing methods and styles and their suitability to different tasks.
  • appreciate the wider use of documentation in evaluating, promoting, and supporting projects.
  • develop a sensitivity to different reader / audience types.
Demonstrated the communication skills necessary to:
  • be able to write effective and clear documentation.
  • be able to use one of each major kind of documentation development and delivery tool.

Contact hours

2 hrs lectures/wk, 2 hrs laboratories/wk

Workload

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

Unit relationships

Prerequisites

One of FIT1002, CPE1001, CSE1202, GCO1811, MMS1801, MMS1802, CSE1301

Prohibitions

CSE1305, CSE1402

Teaching and learning method

Teaching approach

The approach to teaching and learning include a weekly two-hour lecture and a two-hour (tutorial/laboratory). Additionally, each student should spend a minimum of 8 to 12 hours for personal study every week and should allocate up to 5 hours per week in some weeks for use of a computer.

Timetable information

For information on timetabling for on-campus classes please refer to MUTTS, http://mutts.monash.edu.au/MUTTS/

Tutorial allocation

On-campus students should register for tutorials/laboratories using the Allocate+ system: http://allocate.its.monash.edu.au/

Unit Schedule

Week Date* Topic Study guide References/Readings Key dates
1 01/03/10 Introduction to unit ( Theory in lecture - hands-on pracs with XML, Latex etc in Tute/Lab classes for this unit) - Week 1 - web engineering, document engineering Refer to prescribed & recommended lists and lecture notes & Tute/Lab material for each week - for this week - Ch1 - Pressman & Ch.1 - Glushko Both prescribed texts - each week, Glushko's text - see recommended text list  
2 08/03/10 Web eng-tools & techniques, Defining XML lnaguages, XML doc languages Ch1 - Pressman & Ch.3 & 4 - Cowan, Ch. 1 & 2 - XML text - Well formed XML Both prescribed texts - each week, Cowan' text - recommended text  
3 15/03/10 Web processes, Communication, team work, collaboration tools, describe what businesses do & how they do it Ch3 & 4 - Pressman & Ch.4 - Glushko, Ch. 3- XML text - XML Name spacing Both prescribed texts - each week, Glushko's text - see recommended text list  
4 22/03/10 Planning, Change & Content mgmt, Single sourcing Ch5 & 16 - Pressman & Ch.4 - Ebner, Ch. 4 - XML text - Validation - XML Both prescribed texts - each week, Ebner's text - see recommended text list  
5 29/03/10 Interoperability, Doc Eng, UC Design Ch 6 & 7 - Glushko, Ch. 5 - XML text - XML Schema Easter holiday time reading - 2nd- 9th apr- Critical thinking, argumentation, writing technique, OED, Linux, emacs Both prescribed texts - each week, Glushko's text - see recommended text list Assignment 1.1 due
Mid semester break
6 12/04/10 Critical thinking, argumentation - 1 hour - Guest lecture, English - 1 hour - LLS lecturer Reference list, Ch. 7- XML text- XPath Writing, English, Argumentation, Critical thinking - from recommended list  
7 19/04/10 Modeling & Analysis modeling, Analyse context of use Ch6 & 7 - Pressman & Ch.8 - Glushko, Ch. 8- XML text - XSLT (Ch 10 & 12 - self study) Both prescribed texts - each week, Glushko's text - see recommended text list  
8 26/04/10 Web app design, interaction design, Test plans I & II Ch8-9 & 15 - Pressman & Ch. 13- XML text - RSS, Ch 17 - Display, CSS Both prescribed texts - each week Assignment 1.2 due
9 03/05/10 Doc design, external & internal design, latex, graphics, xfig, bibtex Reference list, Latex in the lab Latex references in the recommended list  
10 10/05/10 Info design, Functional design, Analyse document components Ch10 & 11 - Pressman & Ch.12 - Glushko, Ch. 18- XML text - XHTML Both prescribed texts - each week, Glushko's text - see recommended text list Ass.2 due - Latex assignment
11 17/05/10 Analyse business process, designing documents for web services Ch.9 & 10 - Glushko, Ch. 19 & 20- XML text - SVG & XForms Both prescribed texts - each week, Glushko's text - see recommended text list  
12 24/05/10 Guest lecture   Both prescribed texts - each week, Glushko's text - see recommended text list Assignment 1.3 due
13 31/05/10 Revision      

*Please note that these dates may only apply to Australian campuses of Monash University. Off-shore students need to check the dates with their unit leader.

Improvements to this unit

The unit has been extensively modified as a result of student feedback and feedback from the previous lecturer. The focus has changed from technical writing to technical documentation in the context of software engineering. Latex is not used exclusively for writing/documentation anymore in this unit. XML is chosen as the language of choice in document engineering and technical documentation for software engineers.

Monquest evaluation is planned for this unit.

Unit Resources

Prescribed text(s) and readings

Prescribed texts:

Roger S. Pressman and David Lowe (2009). Web Engineering - A Practitoner's approach, McGraw-Hill.

David Hunter et al. (2007). Beginning XML 4th ed., Wiley Publ.

Recommended text(s) and readings

Recommended texts:

Cowan C., XML in Technical Communication, ISTC Books, 2008.

Ebner M., XML-driven Technical Documentation - Advantages of XML-Centered Information Handling, VDM Verlag, 2008.

Glushko R.J. & McGrath T. Document Engineering, MIT Press, 2008.

Carey P. New Perspectives on creating web pages with HTML, XHTML, and XML, 3rd Ed., Cengage Learning Australia.

Holzner S., XML - Go  beyond basics with Ajax, XHTML, XPath 2.0, XSLT 2.0 & XQuery, McGraw-Hill, 2009.

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.S Dobrin, C Keller, C Weisser (2008).

Technical Communication in the 21st Century, Prentice Hall.

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 MUSElab, including: XML, Latex, Firefox, emacs, bibtex, gv, dvips, xfig, SVN.

Equipment and consumables required or provided

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

Study resources

Study resources we will provide for your study are:

  • Weekly detailed lecture notes;
  • Laboratory assignments;
  • Sample documents;
  • This Unit Guide outlining the administrative information and teaching information for the unit;
  • The unit web site on Moodle, where resources outlined above will be made available.

Assessment

Overview

Practical Examination: 50%; In-semester assessment: 50%

Faculty assessment policy

To pass a unit which includes an examination as part of the assessment a student must obtain:

  • 40% or more in the unit's examination, and
  • 40% or more in the unit's total 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 total assessment, and the total mark for the unit is greater than 50% then a mark of no greater than 49-N will be recorded for the unit.

50%  - lab assignments plus weekly hurdle exercises in the lab; 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 each of the unit's non-examination assessment - all assignments
  •  hurdle exercises from XML text in tute/labs - atleast 50% or more must be completed & stored weekly on moodle  
     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 total assessment, and the total mark for the unit is greater than 50% then a mark of no greater than 49-N will be recorded for the unit.

Assignment tasks

Assignment coversheets

Assignment coversheets are available via "Student Forms" on the Faculty website: http://www.infotech.monash.edu.au/resources/student/forms/
You MUST submit a completed coversheet with all assignments, ensuring that the plagiarism declaration section is signed.

Assignment submission and return procedures, and assessment criteria will be specified with each assignment.

  • Assignment task 1
    Title:
    Assignment 1.1
    Description:
    Produce a consolidated technical documentation for:  a) planning and b) software requirement specification (SRS) in XML as per IEEE Standard.

    Detailed description will be made available on moodle.
    Weighting:
    12%
    Due date:
    Week 5 Fri, 2nd Apr 2010, 4pm (submission through moodle)
    Remarks:
    Please do a trial submission before the above due date to check that moodle submission works ok for you for this unit, as from friday 2nd, students have a Easter break  for a week.

    All assignments MUST be completed. Refer to assessment policy for the unit.
  • Assignment task 2
    Title:
    Assignment 1.2
    Description:
    Produce a consolidated technical documentation for modeling & design for the case study referred to in the text book by Pressman & Lowe.Detailed description will be made available on moodle.
    Weighting:
    12%
    Due date:
    Week 8 - Fri 30 Apr 4pm (submission through moodle)
    Remarks:
    All assignments MUST be completed. Refer to assessment policy for the unit.
  • Assignment task 3
    Title:
    Assignment 1.3
    Description:
    Produce a consolidated technical documentation for testing as per IEEE Standard for the case study referred to in the text book by Pressman & Lowe.Detailed description will be made available on moodle.
    Weighting:
    12%
    Due date:
    Week 12, Fri 28th May 4pm (submission through moodle)
    Remarks:
    All assignments MUST be completed. Refer to assessment policy for the unit.
  • Assignment task 4
    Title:
    Assignment 2
    Description:
    Report written using latex More details will be made available on moodle.
    Weighting:
    14%
    Due date:
    Week 10, Fri 14th May (submission through moodle)
    Remarks:
    All assignments MUST be completed. Refer to assessment policy for the unit.

Examination

  • Weighting: 50%
    Length:
    Type (open/closed book): Closed book

See Appendix for End of semester special consideration / deferred exams process.

Due dates and extensions

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 not regarded as appropriate reasons for granting extensions. Students are advised to NOT assume that granting of an extension is a matter of course.

Students requesting an extension for any assessment during semester (eg. Assignments, tests or presentations) are required to submit a Special Consideration application form (in-semester exam/assessment task), along with original copies of supporting documentation, directly to their lecturer within two working days before the assessment submission deadline. Lecturers will provide specific outcomes directly to students via email within 2 working days. The lecturer reserves the right to refuse late applications.

A copy of the email or other written communication of an extension must be attached to the assignment submission.

Refer to the Faculty Special consideration webpage or further details and to access application forms: http://www.infotech.monash.edu.au/resources/student/equity/special-consideration.html

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.

Appendix

Please visit the following URL: http://www.infotech.monash.edu.au/units/appendix.html for further information about:

  • Continuous improvement
  • Unit evaluations
  • Communication, participation and feedback
  • Library access
  • Monash University Studies Online (MUSO)
  • Plagiarism, cheating and collusion
  • Register of counselling about plagiarism
  • Non-discriminatory language
  • Students with disability
  • End of semester special consideration / deferred exams