Skip to the content | Change text size
PDF unit guide

FIT2043 Technical documentation for software engineers - Semester 2, 2015

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.

See also Unit timetable information

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

Terence Huynh

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

Based on last year's feedback, no substantial changes were necessary this year.

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:
  1. produce well-organised and clear technical documentation;
  2. 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;
  3. 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;
  4. 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;
  5. evaluate the correctness, appropriateness, and usability of written documentation, and apply strategies to improve these;
  6. 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 Reports and proposals: supporting your decisions with documentation 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
    Remarks:
    This assignment will be assessed against the following Unit Learning Outcomes:

    1. produce well-organised and clear technical documentation
    4. 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
    5. evaluate the correctness, appropriateness, and usability of written documentation, and apply strategies to improve these
  • 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
    Remarks:
    This assignment will be assessed against the following Unit Learning Outcomes:

    3. 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
    5. evaluate the correctness, appropriateness, and usability of written documentation, and apply strategies to improve these
    6. correctly use specified software tools to create and publish technical documentation
  • 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
    Remarks:
    This assignment will be assessed against the following Unit Learning Outcomes:

    1. produce well-organised and clear technical documentation
    3. 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
    4. 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
    5. evaluate the correctness, appropriateness, and usability of written documentation, and apply strategies to improve these
    6. correctly use specified software tools to create and publish technical documentation

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.
    Remarks:
    This exam addresses the following Unit Learning Outcomes:

    2. 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
    3. 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
    5. evaluate the correctness, appropriateness, and usability of written documentation, and apply strategies to improve these
    6. correctly use specified software tools to create and publish technical documentation.

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

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/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 electronic submission). 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: Notepad++, Chrome, Firefox, and TortoiseSVN.

Technological Requirements

Students must check Moodle at least once a week for announcements.  We recommend that students check the discussion forums as well as the unit news forum, since unit staff will often post helpful information in response to student queries.

Students are encouraged to bring their laptop to their lab classes but this is not mandatory as all required software is installed on the lab computers.

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

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.

Other

Engineers Australia Stage 1 competencies

This unit is a core unit in the Bachelor of Software Engineering accredited by Engineers Australia. Engineers Australia Accreditation Policy of Professional Engineering Programs requires that programs demonstrate how engineering graduates are prepared for entry to the profession and achieve Stage 1 competencies. The following information describes how this unit contributes to the development of these competencies for the Bachelor of Software Engineering. (Note: not all competencies may be emphasised in this unit).

Stage 1 competency How the compency is developed in this unit
 1. Knowledge and Skills base  
 1.1. Comprehension, theory based understanding of the underpinning natural and physical sciences and the engineering fundamentals applicable to the engineering discipline. Not covered in this unit
 1.2. Conceptual understanding of the mathematics, numerical analysis, statistics, and computer and information sciences, which underpin the engineering discipline. Although these skills are not directly assessed in this unit, students do need to be able to understand the fundamentals of declarative programming in order to make the best use of XSLT in their first assignment.
 1.3. In-depth understanding of specialist bodies of knowledge within the engineering discipline. Students are introduced to the technologies and concepts behind single-source document engineering in Assignment 1.
 1.4. Discernment of knowledge development and research directions within th engineering discipline. Not covered in this unit.

 1.5. Knowledge of engineering design practice and contextual factors impacting the engineering discipline.

All documentation that the students produce for their assignments needs to take into account the technical and business context of the piece in question: the background knowledge that the audience is likely to have, and the role of the documentation in the Software Engineering or business workflow.
 1.6. Understanding of the scope, principles, norms, accountabilities and bounds of sustainable engineering practice in the specific discipline. The documents that students produce for their assignments needs to be appropriate for its intended purpose. In the case of internal (team-facing) documentation, this entails understanding the normal roles and responsibilities in Software Engineering and software development teams.
 2. Engineering application ability  
 2.1. Application of established engineering methods to complex engineering problem solving. Although design is not taught in depth in this unit, as part of their assignment on technical reviews, students are required to review and improve the architecture of a simple system using techniques and principles they have learned in previous units.
 2.2 Fluent application of engineering techniques, tools and resources. All assignments, as well as the final exam, require the application of tools to create documents.
 2.3. Application of systematic engineering synthesis and design processes. As part of their assignment on technical reviews, students are required to review and improve the architecture of a simple system. Students also need to develop their XSLT templates systematically in order to succeed in Assignment 1.
 2.4. Application of systematic approaches to the conduct and management of engineering projects. This is not directly assessed. Students work in small groups on Assignment 1 and may choose to use project management techniques they have learned in other units, but this is neither required nor enforced.
 3. Professional and personal attributes  
 3.1. Ethical conduct and professional accountability. All students are expected to abide by Monash's academic honesty policies when producing documentation.
 3.2. Effective oral and written communication in professional and lay domains. In assignments, students write both internal (i.e. team-facing) and external (i.e. client-facing) documents. They need to be able to adapt their writing style to readers of a variety of levels of technical knowledge. They are also asked in their final exam to critique and improve poorly-written documentation to improve its accessibility, and to detect and describe logical fallacies.
 3.3. Creative, innovative and proactive demeanour. In Assignment 1, students design XSLT templates to display information in HTML format. This allows for many creative approaches to document layout and look-and-feel, and good visual design is rewarded.
 3.4. Professional use and management of information. Not covered in this unit.
 3.5. Orderly management of self, and professional conduct. Students are expected to conduct themselves in a professional manner in the classroom, and to produce documentation using a style and mode of expression that would be suitable for showing to clients and colleagues in industry.
 3.6. Effective team membership and team leadership. Students work in small teams on Assignment 1. Although students' practices are not monitored in detail, more effective teamwork generally results in more efficient use of time and hence a better product.

Relationship between Unit Learning Outcomes and BSE Course Outcomes

No. CO 1 CO 2 CO 3 CO 4 CO 5 CO 6 CO 7 C0 8 CO 9 CO 10 CO 11 CO 12 CO 13
 1    X  X        X  X  X    X    
 2    X  X  X        X          
 3    X X                X    
 4                  X    X    
 5            X    X  X    X    
 6              X        X    

Relationship between Unit Learning Outcomes and Assessments

No. Assignments Quizzes Practical Exercises Exam
1  X      
2        X
3  X      X
4  X      
5  X      X
6  X    X  X