[an error occurred while processing this directive] [an error occurred while processing this directive]
[an error occurred while processing this directive]
[an error occurred while processing this directive]
Monash University

FIT2043 Technical documentation for software engineers - Semester 2, 2011

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.

Mode of Delivery

Clayton (Day)

Contact Hours

2 hrs lectures/wk, 2 hrs laboratories/wk

Workload

Students will be expected to spend a total of 12 hours per week during semester on this unit as follows:

Lectures: 2 hours per week
Tutorials/Lab Sessions: 2 hours per week per prac lab
and up to an additional 8 hours in some weeks for completing lab and project work, private study and revision.

Unit Relationships

Prohibitions

CSE1305, CSE1402

Prerequisites

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

Chief Examiner

Dr David Squire

Campus Lecturer

Clayton

David Squire

Contact hours: the lab classes and the Moodle discussion forum are the primary places for communication. Other consultation time will be announced on Moodle.

Tutors

Clayton

Robyn McNamara

Nabeel Mohammed

Academic Overview

Learning Objectives

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.

Graduate Attributes

Monash prepares its graduates to be:
  1. responsible and effective global citizens who:
    1. engage in an internationalised world
    2. exhibit cross-cultural competence
    3. demonstrate ethical values
  2. critical and creative scholars who:
    1. produce innovative solutions to problems
    2. apply research skills to a range of challenges
    3. communicate perceptively and effectively

Assessment Summary

Examination (2 hours): 50%; In-semester assessment: 50%

Assessment Task Value Due Date
Assignment 1.1 12% Week 5: Friday, 26 August 2011
Assignment 1.2 12% Week 8: Friday 16 September 2011
Assignment 1.3 12% Week 12: Friday 21 October 2011
Assignment 2 14% Week 10: Friday 7 October 2011
Examination 1 50% To be advised

Teaching Approach

Lecture and tutorials or problem classes
This teaching and learning approach provides facilitated learning, practical exploration and peer learning.

Feedback

Our feedback to You

Types of feedback you can expect to receive in this unit are:
  • Informal feedback on progress in labs/tutes
  • Graded assignments with comments
  • Other: Responses to questions on the Moodle discussion forum

Your feedback to Us

Monash is committed to excellence in education and regularly seeks feedback from students, employers and staff. One of the key formal ways students have to provide feedback is through SETU, Student Evaluation of Teacher and Unit. The University's student evaluation policy requires that every unit is evaluated each year. Students are strongly encouraged to complete the surveys. The feedback is anonymous and provides the Faculty with evidence of aspects that students are satisfied and areas for improvement.

For more information on Monash's educational strategy, and on student evaluations, see:
http://www.monash.edu.au/about/monash-directions/directions.html
http://www.policy.monash.edu/policy-bank/academic/education/quality/student-evaluation-policy.html

Previous Student Evaluations of this unit

If you wish to view how previous students rated this unit, please go to
https://emuapps.monash.edu.au/unitevaluations/index.jsp

Required Resources

Software:

The software required will be available in the University computer labs, including: XML, LaTeX, Firefox, emacs, bibtex, gv, dvips, xfig, SVN.
You will need access to a Windows, also available in computer labs and Linux system (freely available) and the internet.

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.

You will need access to the prescribed texts, which are available in the library.

Unit Schedule

Week Activities Assessment
0   No formal assessment or activities are undertaken in week 0
1 Introduction to unit, web engineering, document engineering  
2 Web engineering tools & techniques, Defining XML languages, XML document languages  
3 Web processes, communication, team work, collaboration tools, describing what businesses do & how they do it  
4 Planning, Change & Content management, Single sourcing  
5 Interoperability, Document Engineering, User-Centred Design Assignment 1.1 due on Friday 26 August 2011
6 Critical thinking, Argumentation; English (guest lecture)  
7 Modeling & Analysis, Analysing context of use  
8 Web application design, interaction design, Test plans I & II Assignment 1.2 due on Friday 16 September 2011
9 Document design, external & internal design, LaTeX, graphics, xfig, bibtex  
10 Information design, Functional design, Analysing document components Assignment 2 due on Friday 7 October 2011
11 Analysing business process, designing documents for web services  
12 Revision Assignment 1.3 due on Friday 21 October 2011
  SWOT VAC No formal assessment is undertaken in SWOT VAC
  Examination period LINK to Assessment Policy: http://policy.monash.edu.au/policy-bank/
academic/education/assessment/
assessment-in-coursework-policy.html

*Unit Schedule details will be maintained and communicated to you via your MUSO (Blackboard or Moodle) learning system.

Assessment Requirements

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

Assessment Tasks

Participation

To meet the learning objectives for this unit at least 50% of the weekly lab exercises must be completed and submitted.This is a hurdle requirement.

A student who does not meet all these hurdles can get a maximum of 49-N for the unit.

For applying for special consideration refer to the link provided under 'Extensions and penalties' at the end of this section.

  • Assessment task 1
    Title:
    Assignment 1.1
    Description:
    Produce consolidated technical documentation for:  a) planning and b) software requirement specification (SRS) in XML as per the IEEE Standard. A detailed description will be made available on Moodle.
    Weighting:
    12%
    Criteria for assessment:

    Work will be assessed for:

    • adherence to the standards specified,
    • as well as organization,
    • presentation,
    • and qualiity of expression.
    Due date:
    Week 5: Friday, 26 August 2011
    Remarks:
    All assignments MUST be completed.
  • Assessment task 2
    Title:
    Assignment 1.2
    Description:
    Produce consolidated technical documentation for modelling & design for the case study referred to in the text book by Pressman & Lowe. A detailed description will be made available on Moodle.
    Weighting:
    12%
    Criteria for assessment:

    Work will be assessed for:

    • adherence to the standards specified,
    • as well as organization,
    • presentation,
    • and qualiity of expression.
    Due date:
    Week 8: Friday 16 September 2011
    Remarks:
    All assignments MUST be completed.
  • Assessment task 3
    Title:
    Assignment 1.3
    Description:
    Produce consolidated technical documentation for testing as per IEEE Standard for the case study referred to in the text book by Pressman & Lowe. A detailed description will be made available on moodle.
    Weighting:
    12%
    Criteria for assessment:

    Work will be assessed for

    • adherence to the standards specified,
    • as well as organization,
    • presentation,
    • and qualiity of expression.
    Due date:
    Week 12: Friday 21 October 2011
    Remarks:
    All assignments MUST be completed.
  • Assessment task 4
    Title:
    Assignment 2
    Description:
    Report written using LaTeX. More details will be made available on Moodle.
    Weighting:
    14%
    Criteria for assessment:

    Work will be assessed for

    • adherence to the standards specified,
    • as well as organization,
    • presentation,
    • and qualiity of expression.
    Due date:
    Week 10: Friday 7 October 2011
    Remarks:
    All assignments MUST be completed.

Examinations

  • Examination 1
    Weighting:
    50%
    Length:
    Type (open/closed book):
    Closed book
    Electronic devices allowed in the exam:
    None

Assignment submission

It is a University requirement (http://www.policy.monash.edu/policy-bank/academic/education/conduct/plagiarism-procedures.html) for students to submit an assignment coversheet for each assessment item. Faculty Assignment coversheets can be found at http://www.infotech.monash.edu.au/resources/student/forms/. Please check with your Lecturer on the submission method for your assignment coversheet (e.g. attach a file to the online assignment submission, hand-in a hard copy, or use an online quiz).

Extensions and penalties

Submission must be made by the due date otherwise penalties will be enforced.

You must negotiate any extensions formally with your campus unit leader via the in-semester special consideration process: http://www.infotech.monash.edu.au/resources/student/equity/special-consideration.html.

Returning assignments

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

Resubmission of assignments

Assigments cannot be resubmitted.

Referencing requirements

All sources used must be referenced using either the Chicago or the Harvard citation convention.

See Monash link for Citing and Referencing: http://www.lib.monash.edu.au/tutorials/citing/

Other Information

Policies

Monash has educational policies, procedures and guidelines, which are designed to ensure that staff and students are aware of the University's academic standards, and to provide advice on how they might uphold them. You can find Monash's Education Policies at:
http://policy.monash.edu.au/policy-bank/academic/education/index.html

Key educational policies include:

Student services

The University provides many different kinds of support services for you. Contact your tutor if you need advice and see the range of services available at www.monash.edu.au/students The Monash University Library provides a range of services and resources that enable you to save time and be more effective in your learning and research. Go to http://www.lib.monash.edu.au or the library tab in my.monash portal for more information. Students who have a disability or medical condition are welcome to contact the Disability Liaison Unit to discuss academic support services. Disability Liaison Officers (DLOs) visit all Victorian campuses on a regular basis

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.

You will need access to the prescribed texts, which are available in the library.

READING LIST:

Recommended text(s) and readings:

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.

[an error occurred while processing this directive]