Skip to the content | Change text size
PDF unit guide

FIT2043 Technical documentation for software engineers - Semester 2, 2014

This unit covers problems with paper-based and on-line documentation; types of technical documentation used in software engineering; the role of various different forms of technical documentation in the software development process; document specifications; the context of technical writing; the writing process (analysis, planning, generation, testing, revision and maintenance of written texts); document publication techniques (such SGML, LaTeX, and/or 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)

Workload Requirements

Minimum total expected workload equals 12 hours per week comprising:

(a.) Contact hours for on-campus students:

  • Two hour of lectures
  • One 2-hour laboratory

(b.) Additional requirements (all students):

  • A minimum of 8 hours independent study per week for completing lab and project work, private study and revision.

Unit Relationships

Prohibitions

CSE1305, CSE1402

Prerequisites

FIT1010 or FIT1002

Chief Examiner

Campus Lecturer

Clayton

Robyn McNamara

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

Andre Oboler

Resmi Hasankolli

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

Academic Overview

Learning Outcomes

On successful completion of this unit, students should be able to:
  • produce well-organised and clear technical documentation;
  • explain the purposes and uses of the different types of technical documentation, including code documentation, internal design documentation, external design documentation, reference manuals, guides, and tutorials;
  • distinguish between the different types of tools for producing documentation (text editors, formatters, typesetters, desktop publishers, graphics tools, printing and viewing tools) and select tools that are appropriate for specified applications;
  • produce technical documentation that is written in an appropriate style and at an appropriate level for different classes of readers, including fellow software engineering professionals, managers, clients, and end-users;
  • evaluate the correctness, appropriateness, and usability of written documentation, and apply strategies to improve these;
  • correctly use specified software tools to create and publish technical documentation.

Unit Schedule

Week Activities Assessment
0   No formal assessment or activities are undertaken in week 0
1 Introduction to Technical Documentation  
2 Register, tone, and audience: understanding the context of writing  
3 Documentation standards  
4 Documenting the software development process  
5 Introduction to XML and XSLT  
6 Single-source document production Assignment 1
7 Documenting requirements: elicitation, analysis, and traceability  
8 Documenting software design and architecture  
9 Documenting implementation: writing for your peers Assignment 2
10 Documentation and quality assurance  
11 Writing for technical and nontechnical audiences  
12 Working with technical writers Assignment 3
  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.

Teaching Approach

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

Assessment Summary

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

Assessment Task Value Due Date
Assignment 1 15% Friday of Week 6
Assignment 2 15% Friday of Week 8
Assignment 3 20% Friday of Week 12
Examination 1 50% To be advised

Assessment Requirements

Assessment Policy

Assessment Tasks

Participation

  • Assessment task 1
    Title:
    Assignment 1
    Description:
    Write a Project Management Plan that documents how your team will approach Assignments 2 and 3.
    Weighting:
    15%
    Criteria for assessment:

    Work will be assessed for:

    • adherence to the standards specified,
    • organisation,
    • presentation,
    • quality of expression.

    Students will work in small teams or pairs, and will be expected to keep track of the amount of work done by each team member.  Each team member will achieve the same mark unless the evidence presented shows a substantial disparity in effort or achievement.

    Due date:
    Friday of Week 6
  • Assessment task 2
    Title:
    Assignment 2
    Description:
    Create and apply an XML Schema for Project Management Plans.  Mark up your own Project Management Plan (from Assignment 1) in this schema, and also a Project Management Plan provided by the lecturer.  Produce XSLT transformations that extract different subsets of these Project Management Plans and transform them to HTML.

    Further details about the required submissions will be available on the unit Moodle page during semester.
    Weighting:
    15%
    Criteria for assessment:

    Work will be assessed for:

    • adherence to the standards specified,
    • organisation,
    • presentation,
    • quality of expression.

    Students will work in small teams or pairs, and will be expected to keep track of the amount of work done by each team member.  Each team member will achieve the same mark unless the evidence presented shows a substantial disparity in effort or achievement.

    Students will be expected to apply the policies and practices outlined in their team's Project Management Plan, unless they have the consent of the lecturer.

    Due date:
    Friday of Week 8
  • Assessment task 3
    Title:
    Assignment 3
    Description:
    Given a set of technical requirements, write a Test Plan to manage the testing a system that implements these requirements.  Encode this test plan according to a suitable XML schema and develop XSLT transformations to present all or part of it in HTML.

    Further information on the required submissions will be provided on the Moodle site during semester.
    Weighting:
    20%
    Criteria for assessment:

    Work will be assessed for:

    • adherence to the standards specified,
    • organisation,
    • presentation,
    • quality of expression.

    Students will work in small teams or pairs, and will be expected to keep track of the amount of work done by each team member.  Each team member will achieve the same mark unless the evidence presented shows a substantial disparity in effort or achievement.

    Students will be expected to apply the policies and practices outlined in their team's Project Management Plan, unless they have the consent of the lecturer.

    Due date:
    Friday of Week 12

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.

Fowler M. UML Distilled, 3rd Ed., Pearson Education, 2003.

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 (if applicable to the unit)
http://readinglists.lib.monash.edu/index.html

Faculty of Information Technology Style Guide

Feedback to you

Examination/other end-of-semester assessment feedback may take the form of feedback classes, provision of sample answers or other group feedback after official results have been published. Please check with your lecturer on the feedback provided and take advantage of this prior to requesting individual consultations with staff. If your unit has an examination, you may request to view your examination script booklet, see http://intranet.monash.edu.au/infotech/resources/students/procedures/request-to-view-exam-scripts.html

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/student-academic-integrity-managing-plagiarism-collusion-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:

Faculty resources and policies

Important student resources including Faculty policies are located at http://intranet.monash.edu.au/infotech/resources/students/

Graduate Attributes Policy

Student Charter

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.