Writing Technical Documents
Overview
Whether the task is to describe a simple procedure or producing a user guide - documentation is often the bane of the Information Technology professional. Technical documentation is a job or project requirement that must be completed and does not go away with time.
Once you get started on the writing task, the ultimate goal is to produce the most effective and usable documentation for the audience in the least amount of time.
This course covers key topics in the documentation development life cycle with a focus on effectively writing a document: information planning, content specification and implementation. Each stage of the experienced writer's process - inventing, drafting and revising - is reviewed within the life cycle. Techniques for drafting quickly, effective revision and clear communications will be covered.
Writing tips, guidelines and an editing checklist will be provided along with practical examples used for discussion.
Intended For
- Analysts and Subject Matter Experts tasked with software documentation, e.g. user guides, training materials, help materials
- Developers and other team members responsible for project documentation
- System administrators responsible for operations and maintenance documentation
- Project managers and assistants accountable for project documentation
- IT professionals who are just starting to work as technical communicators.
Prerequisites
Participants are expected to be familiar with commonly used Information Technology and word processing terminology.
Learning outcomes
By the end of this course, participants will be able to:
- Use new techniques to create effective technical documentation painlessly
- Explain the importance of knowing document purpose and audience
- Identify the basics of document development
- Explain the importance of U.S.E. (Understand, Simplify and Explain)
- List common attributes of well-written documentation
- List common editing checks.
Content
Introduction
- Background
- Question - How many developers does it take...
- Why are we here?
- Technical communications defined
Bottom Line - Getting the writing done
- Overview - how does a life cycle fit in with the real work?
- Focus: Audience and purpose
- Focus: Working quickly and effectively
Documentation Life Cycle (how to make it work for you)
- Information Planning
- Content Specification
- Implementation
- Production, Evaluation and Maintenance
Documentation habits to make life easier
- Hints and Tips
- The skinny on developing specific types of documentation
- The good, the bad and the ugly - document review
Summary
Method Used
A mix of lecture, discussion and exercises will be used to allow the participants to understand presented techniques and gain hands-on practice. Real world software industry examples and in-class exercises will be used extensively.
