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

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.

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

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.monash.edu.au/exams/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/

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

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: www.policy.monash.edu.au/policy-bank/academic/education/index.html

Key educational policies include:

Graduate Attributes Policy

http://www.policy.monash.edu/policy-bank/academic/education/management/monash-graduate-attributes-policy.html

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 http://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/.

Monash University Library

The Monash University Library provides a range of services, resources and programs that enable you to save time and be more effective in your learning and research. Go to 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/.

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

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 the Student Evaluation of Teaching and Units (SETU) survey. 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, see:

www.monash.edu.au/about/monash-directions and on student evaluations, see: 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

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

[an error occurred while processing this directive]