Technical writing overview EE
From Wikiversity
- back to Technical Writing Level 1
[edit] Introduction
This overview module and the following modules have been written intentionally in the style of a technical document. This is so that the reader sees the type of content needed for technical documents from the outset. The language of the document has been kept simple to allow easy translation. Where ever possible the modules conform to the rules they state. These modules have been taught to small (eight student) classes of students. Each module takes 1 hour to teach. Additional examples and exercises were used.
Technical Writing is a Discipline.
Technical writing is not difficult.
In this module and the modules that follow there are a set of rules that must be applied.
Most of these rules apply to all technical writing, some rules only apply to certain types of documents.
Most of the rules are independent of the style used.
If you learn the rules and apply them then you will write better documents.
It is easier to write using a rigid set of rules than to have no rules.
The rules also help people like:
- Business (System) Analysts
- Project and Product Managers
- Solution (System) Architects
[edit] Technical Writing Rules
The basic rules are:
- Write simple sentences
- Use words that your reader will understand
- Use lists
- Use pictures
- Use consistent terminology
- Do not waste your reader's time by explaining things that they already know
[edit] What is the difference between a Technical writer and a Technical communicator?
- A Technical writer is the old term and a Technical writer writes documents
- A Technical communicator is the new American term for the same job acknowledging that the writer needs to create and modify diagrams
Technical writers produce written and visual information for customers.
[edit] Technical writers write the following types of document
[edit] To design and improve the product
- Requirement specifications, that document the features required in the product
- Development requests, that document tasks for developers
- Change requests, that document new features that the customer wants
- Design Specs,what a product should look like when it is manufactured
[edit] To sell the product
- Technical and product briefs
- Product brochures
- Web sites
- Press releases
[edit] To help the customer administer the product
- User guides
- Configuration guides
- Administration guides
- Data sheets
- Maintenance and trouble shooting guides that show the administrator and experienced user how to configure and troubleshoot the product
[edit] To help the staff of the customer operate the product
- Use-case based tutorials
- Step-by-step task lists
- On-line help in CHM or HTML
[edit] To test and install the product
- Test cases, to test the product and detail the required functionality
- Universal Acceptance Test (UAT), test cases for the customer to confirm that every function that they required is working in the product
- Installation guides so that the product can be installed safely
- Requirements and Functional Specifications (EE) document the needs, goals, and environment of the product users and then how those will be translated into functions in the product.
- Design documents describe the workings and interactions of the system.
- Control documents communicate project standards, configuration, schedule and work tasks.
[edit] Management Documentation
Management Documentation includes:
- Cost and schedule estimates
- Complex documentation project administration
- Setting standards and procedures
- Information management
[edit] What tools do Technical writers use?
A Technical writer's primary tool is language. A Technical writer also uses
- Word processors ( MS Word, Open Office)
- Web tools
- Graphics packages
- Content management systems (CMS)
- Wiki
- Confuence
- Madcap Flare
- Author IT
- Docbook
- Robo Help
- Screen shot capturing tools
- MWSnap (Free-ware)
[edit] The Essential Skills of a Technical Writer
These skills are important:
1. The ability to use a computer
It is possible to write manuals with just paper and a pen but most people don't.
Most products include software that require screen-shots to explain fully, screen-shots require a computer.
2. The ability to write clearly
Technical writers
- Study complicated things
- Remove all doubt about a subject
- Explain them in simple terms
- Add diagrams or screen-shots
- Define abbreviations
- Avoid
- Passive sentences (e.g. "Mistakes have been made.")
- Long sentences
3. The ability to show ideas graphically
If you show an idea with a picture or diagram, then the reader understands the concepts better
4. The ability to Listen
You must listen carefully to the experts and then express their concepts
[edit] Basic Technical Writing
The process of writing
- Plan the document
- Collect and organise information
- Find out who will read the document
- Draft the document
- Revise the document
- Get a colleague to edit the document for style and language
- Get experts to validate the information
- Publish the document
The Wikipedia definition of Technical Communication :
- Personas (EE) How to identify and analyse your readers
Explore how Wiki can be used for delivering user-oriented instructions.
[edit] End of Lesson test
- What does a Technical writer do?
- What is the difference between a Technical writer and a Technical communicator?
- What sort of documents do Technical writers write?
- What skills does a Technical writer need?
- What sort of people become Technical writers?
- Why are you on this course? (unmarked supplementary question)
[edit] References
Forward to next module Personas (EE) How to use the correct language for the people who will read the documents
How to edit Wiki
back to Technical Writing Level 1 Test
The next unit Personas (EE) How to use the correct language for the people who will read the documents
