[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 1, 2012

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

Consultation 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

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.

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, 30 March 2012
Assignment 1.2 12% Week 8: Friday 27 April 2012
Assignment 1.3 12% Week 12: Friday 25 May 2012
Assignment 2 14% Week 10: Friday 11 May 2012
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

This year the unit will be updated to cover modern web documentation standards such as CSS2.

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

Required Resources

Please check with your lecturer before purchasing any Required Resources. Prescribed texts are available for you to borrow in the library, and prescribed software is available in student labs.

Software:

The software required will be available in the University computer labs, including: LaTeX, Texmaker, Firefox, SVN, and text editors.

Recommended text(s)

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

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

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 30 March 2012
6 Critical thinking, Argumentation; English  
7 Modeling & Analysis, Analysing context of use  
8 Web application design, interaction design, Test plans I & II Assignment 1.2 due on Friday 27 April 2012
9 Document design, external & internal design, LaTeX, graphics, xfig, bibtex  
10 Information design, Functional design, Analysing document components Assignment 2 due on Friday 11 May 2012
11 Analysing business process, designing documents for web services  
12 Revision Assignment 1.3 due on Friday 25 May 2012
  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

Faculty Policy - Unit Assessment Hurdles (http://www.infotech.monash.edu.au/resources/staff/edgov/policies/assessment-examinations/unit-assessment-hurdles.html)

Assessment Tasks

Participation

  • Assessment task 1
    Title:
    Assignment 1.1
    Description:
    Create and apply an XML Schema for a Software Requirements Specification. 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 organisation,
    • presentation,
    • and quality of expression.
    Due date:
    Week 5: Friday, 30 March 2012
  • Assessment task 2
    Title:
    Assignment 1.2
    Description:
    Create and apply an XML Schema for a Technical Review. You will be provided with design documentation corresponding to the scenario used in Assignment 1.1. You will review and correct this documentation. 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 organisation,
    • presentation,
    • and quality of expression.
    Due date:
    Week 8: Friday 27 April 2012
  • Assessment task 3
    Title:
    Assignment 1.3
    Description:
    Document Use Cases from the scenario used in Assignments 1.1 and 1.2.
    Weighting:
    12%
    Criteria for assessment:

    Work will be assessed for:

    • adherence to the standards specified,
    • as well as organisation,
    • presentation,
    • and quality of expression.
    Due date:
    Week 12: Friday 25 May 2012
  • Assessment task 4
    Title:
    Assignment 2
    Description:
    Format a technical article for a conference 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 organisation,
    • presentation,
    • and quality of expression.
    Due date:
    Week 10: Friday 11 May 2012

Examinations

  • Examination 1
    Weighting:
    50%
    Length:
    2 hours
    Type (open/closed book):
    Open book
    Electronic devices allowed in the exam:
    The exam is conducted on-line in the FIT labs. Students are permitted to use the internet passively, but must not upload or post anything during the exam.

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

Online submission

If Electronic Submission has been approved for your unit, please submit your work via the VLE site for this unit, which you can access via links in the my.monash portal.

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. For Sunway see http://www.monash.edu.my/Student-services, and for South Africa see http://www.monash.ac.za/current/

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. At Sunway, visit the Library and Learning Commons at http://www.lib.monash.edu.my/. At South Africa visit http://www.lib.monash.ac.za/.

Academic support services may be available for students who have a disability or medical condition. Registration with the Disability Liaison Unit is required. Further information is available as follows:

  • Website: http://monash.edu/equity-diversity/disability/index.html;
  • Email: dlu@monash.edu
  • Drop In: Equity and Diversity Centre, Level 1 Gallery Building (Building 55), Monash University, Clayton Campus, or Student Community Services Department, Level 2, Building 2, Monash University, Sunway Campus
  • Telephone: 03 9905 5704, or contact the Student Advisor, Student Commuity Services at 03 55146018 at Sunway

Reading list

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]