Skip to the content | Change text size
PDF unit guide

FIT2043 Technical documentation for software engineers - Semester 2, 2013

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 requirements

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

FIT1010 or FIT1002

Chief Examiner

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.

Academic Overview

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.

Unit Schedule

Week Activities Assessment
0   No formal assessment or activities are undertaken in week 0
1 Introduction to Document Engineering; Introduction to XML  
2 XML Languages  
3 XML Stylesheets; Version Control with Subversion  
4 Single Sourcing; Software Requirements  
5 Argumentation; XSLT Basics Assignment 1.1 due on Friday 30 August 2013
6 More XSLT; UML Class Diagrams  
7 Introduction to LaTeX  
8 Technical Reviews; Use Cases Assignment 1.2 due on Friday 20 September 2013
9 Professional Writing  
10 Plagiarism; Citations, Quotations, and BibTeX Assignment 2 due on Friday 11 October 2013
11 The Art and Science of Technical Writing; Communication between Software Engineers and Technical Writers  
12 Revision Assignment 1.3 due on Friday 25 October 2013
  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 learning system.

Assessment Summary

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

Assessment Task Value Due Date
Assignment 1.1 12% Friday of Week 5
Assignment 1.2 12% Friday of Week 8
Assignment 1.3 12% Friday of Week 12
Assignment 2 14% Friday of Week 10
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.

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)

Academic Integrity - Please see the Demystifying Citing and Referencing tutorial at http://lib.monash.edu/tutorials/citing/

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:
    Friday of Week 5
  • 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:
    Friday of Week 8
  • 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:
    Friday of Week 12
  • 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:
    Friday of Week 10

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.

Learning resources

Reading list

Roger S. Pressman and David Lowe, Web Engineering - A Practitioner's approach, McGraw-Hill, 2009Cowan 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 Edition).

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.

Monash Library Unit Reading List
http://readinglists.lib.monash.edu/index.html

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

Extensions and penalties

Returning assignments

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/

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). Please note that it is your responsibility to retain copies of your assessments.

Online submission

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

Required Resources

Please check with your lecturer before purchasing any Required Resources. Limited copies of 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.

Other Information

Policies

Graduate Attributes Policy

Student services

Monash University Library

Disability Liaison Unit

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.

Your feedback to Us

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

Other

Some important texts for the unit are available on-line from the library. See http://readinglists.lib.monash.edu/lists/23C791C3-B2B6-B32C-E512-81D7B5D84FB7.html