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.
Minimum total expected workload equals 12 hours per week comprising:
(a.) Contact hours for on-campus students:
(b.) Additional requirements (all students):
See also Unit timetable information
CSE1305, CSE1402
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.
Andre Oboler
Terence Huynh
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
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
| 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.
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 |
Faculty Policy - Unit Assessment Hurdles (http://intranet.monash.edu.au/infotech/resources/staff/edgov/policies/assessment-examinations/assessment-hurdles.html)
Academic Integrity - Please see resources and tutorials at http://www.monash.edu/library/skills/resources/tutorials/academic-integrity/
Work will be assessed for:
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.
Work will be assessed for:
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.
Work will be assessed for:
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.
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
Types of feedback you can expect to receive in this unit are:
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
Assigments cannot be resubmitted.
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/
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.
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.
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.
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.
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
Important student resources including Faculty policies are located at http://intranet.monash.edu.au/infotech/resources/students/
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 Malaysia 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, 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 Malaysia, visit the Library and Learning Commons at http://www.lib.monash.edu.my/. At South Africa visit http://www.lib.monash.ac.za/.
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. |
| 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 |
| No. | Assignments | Quizzes | Practical Exercises | Exam |
| 1 | X | |||
| 2 | X | |||
| 3 | X | X | ||
| 4 | X | |||
| 5 | X | X | ||
| 6 | X | X | X |