 |
Technical writing at a glance
What is Technical Writing?
Types of Technical Writing
1. Process Documents
2. Expert-to-Expert Documents
3. End-User Documents
4. Technical Marketing Communications
Business writing vs technical writing
Our technical writing expertise
Our skill-sets
Our methodology
Types of Technical Documents
1. Policies
2. Standard Operating Procedures
3. Safe Work Procedures
4. Work Instructions
5. Maintenance/Repair Manuals
6. User Manuals/Guides
7. Software Installation Guides
8. Quick Reference Guides
9. API Documentation
10. Service Level Agreements
11. Media Releases
12. Case Studies
13. Whitepapers
14. Company Documents
15. Request for Proposal
16. Proposals, Tenders or Bids
17. Plans
18. Business Standards
19. Learning/Training Documents
|
What is technical writing?
Technical writing is a niche form of business writing used to record and distribute information to
target audiences on a wide range of technical or other specialised topics.
The first question a technical writer should ask is: who is the audience?
Types of technical writing
Technical writing generally falls into one of four categories. Below are a few examples of documents which may be included
in each category as a guide only, and not exhaustive.
1. Process Documents
Process documents are usually intended for internal use by organisations to share knowledge or provide direction on
how to complete a task, with an emphasis on ensuring consistent, organisation-wide procedures.
These include step-by-step process guides, procedures, work instructions, internal wikis, performance reports,
objectives and key result (OKR) documents and human resource policies and procedures.
2. Expert-to-Expert Documents
Niche technical documents includes research reports, legal documents, case studies and white papers. These
are usually written by experts, for experts, to record approaches to complex, industrial or professional topics.
3. End User Documents
These aim to advise or guide users of a product or service to help them understand the core functionality of a
product, service or procedure and how to deal with any variables. They may include user manuals, legal disclaimers,
employee handbooks, and website help centres.
4. Technical Marketing Communications
Technical marketing writing can best be described as persuasive business-to-business communication. A marketing oriented
technical writer needs to communicate their messages in user-friendly language, to help drive brand awareness
and/or help prospective customers understand the product's core benefits.
Organisations use technical marketing writing for sales pitches, case studies, informational articles, and
even emails to promote or sell their services and products.
Business writing vs technical writing
Technical writing and business writing are similar, but not the same or interchangeable. Most technical writers
specialise in one type or the other, although many professionals can adapt to either. Both styles follow formal
language styles to convey their messages, but their outputs are clearly different.
Technical writing usually adopts a neutral, competent, and professional tone, its primary purpose being
to explain potentially complex topics, often to non-technical readers.
Business writing tones can vary considerably depending on the target audience and purpose. Marketing writing, as a subset of
business writing, is often persuasive in style, and therefore has less in common with technical writing than
other business writing.
The notes below provide examples of the types of documents technical writers produce.
Our technical writing expertise
Our specialist technical writers are professionals who produce technical documentation for information
technology, engineering, other technical, business, and consumer audiences. They prepare information to help users
who use the products includes online help, safe work instructions, policies, procedures, user guides, manuals, white
papers, design specifications, system manuals, project plans, test plans, business correspondence, etc.
Our skill-sets
In addition to sound research, language, writing, and revision skills, our technical writers have skills in:
Information design
Information architecture
Training material development
Illustration/Graphic design
Website design/management
Indexing
Localization/Technical translation
User interfaces
Business analysis
Technical writers are generally not expected to also be subject matter experts (SMEs), although some are, but they still
interview SMEs and conduct the research necessary to write and/or compile technically accurate content.
Document Design: Technical Writing can be a creative process. Document design is a component of technical writing that
increases readability and usability. Technical writers often employ the following six design strategies to plan and create technical
documents:
1. Arrangement refers to the order and organization of visual elements so that readers can see
their structure - how they cohere in groups, how they differ from one another, how they create layers and hierarchies.
2. Emphasis refers to how a document displays important sections through prominence or intensity. This enables the
technical writer to consider how they can show readers important sections, warning, useful tips, etc. through the use
of placement, bolding, colour, and type size.
3. Clarity refers to strategies used to help the receiver decode
the message, to understand it quickly and completely, and, when necessary, to react without ambivalence.
4. Conciseness refers to the "visual bulk and intricacy" of the design, e.g., the number of headings and lists, lines
and boxes, detail of drawings and data displays, size variations, ornateness, and text spacing.
5. Tone is the sound or feel of a document. In addition to language choice, technical writers set the tone
of technical communication through the use of spacing, images, typefaces, etc.
6. Ethos. Technical writers strive to create professional and error-free documentation to establish credibility with
the audience.
Our methodology
Most of us are familiar with the standard Project Management Lifecycle:
1. Initiation; 2. Planning; 3. Execution; 4. Monitoring & Controlling; 5. Closure.
We have borrowed from but modified this model for technical writing, because writing a technical document, or a series of documents,
is best managed as a project, but the model also bears some similarity to the software development life cycle.
Our technical document development life cycle model comprises the following 10 phases:
1: Initiation (clarify approvals, scope, standards and budget, usually with project sponsor or director)
2. Planning and requirements gathering (meetings with stakeholders and SMEs)
3: Audience profiling (identify target audience and user task analysis, including task observations, as appropriate)
4. Content design and format specification (verify organisation's approved styles and standards)
5: Content development (develop draft content and document structure)
6. Edit, format and proofread (complete the draft document and prepare to submit to stakeholders for feedback)
7. Trial execution and feedback (review with SMEs, higher level managers and project sponsor or delegate)
8. Incorporate feedback, edit, gain sign-off to publish. (gain correct organisational approval to publish)
9. Determine review period and process (establish requied review date and embed metadata in document)
10. Publish and monitor. (publish: e.g., hard copy, PDF online, organisation intranet, or html web page.)
11. Closure and maintenance (close writing project and handover to document control to manage maintenance)
Well-written technical documents usually follow formal standards or guidelines. Many companies have internal corporate
style guides that cover specific corporate issues such as logo use, branding, and other aspects of corporate style.
Our final production typically follows an inspection checklist to ensure the quality and uniformity of the published product.
Types of Technical Documents
The notes below provide examples of the types of documents technical writers produce.
1. Policies
Policies are typically a system of guidelines for decision-making and achieve outcomes within an expected
ethical or rational framework. A policy is a statement of intent and is usually implemented through one or
more procedures or protocols.
Policies are generally adopted and promulgated by an organisation?s governance body
and provide a framework for both subjective and objective decision making.
2. Standard Operating Procedures
Standard operating procedures (SOPs) are typically holistic processes which provide guidance to employees on
how to perform workplace tasks.
SOPs are designed to ensure smooth and consistent internal operations and workflows,
by standardising processes and are often accompanied by process maps or flow charts.
3. Safe Work Procedures
Safe Work Procedures (SWPs) can be like SOPs, but typically apply to more manual operations like maintenance
or other operational tasks, where safety is an important element of performing the task.
Typically based on a Job Hazard Analysis (JHA) or similar, SWPs should identify every hazard, consequence and
treatment of that hazard encountered when performing each step of a task, and often include risk assessment
and risk management guidance.
4. Work Instructions
Work Instructions (WIs) can be similar to SOPs or SWPs but are usually targeted at a lower level and
in much greater detail than procedures, and often have a lower approval threshold. Work instructions may get
down to the level of detailed screen captures of system steps or in the case of equipment maintenance, may describe
steps that a semi or unskilled operator can follow. Procedures may be written for (say) a trades qualified maintainer.
However, there is no golden rule about this, and their use can vary widely between organisations.
5. Maintenance / Repair Manuals
Maintenance and/or repair manuals are technical documents intended to provide recommendations and information necessary
to maintain a system or item of equipment effectively. A maintenance manual may include a description of the support
environment, roles and responsibilities of maintenance personnel, regular activities essential to the equipment's safe
operation including warranties, to maximise its efficiency and/or longevity.
A maintenance manual may simply be a compendium of individual SOPs, SWPs and/or WIs, with a consolidated index.
6. User Manuals/Guides
User manuals or guides are instruction manuals written for non-technical end-users, to help them use products which
may range from software to assembling flat-pack furniture. These manuals/guides are generally written in a user-friendly
style, often with simple illustrations to highlight key issues.
7. Software Installation Guides
Computer software should be accompanied by documentation such as an installation guide to assist users through the setup process.
A well-written installation guide may include detailed workflows, video tutorials, FAQs, and a troubleshooting guide.
8. Quick Reference Guides
A Quick Reference Guide (QRG) is typically a short form of a ?how to? document such as a SOP, SWP or WI, with the key information
abbreviated and condensed to a step-by-step checklist, sometimes called a 'cheat sheet'.
Each step may be supported by a simple
diagram or screen capture to elaborate the text instruction, as appropriate. They are difficult to write well, as if they are too
condensed, they are not useful and if too wordy, they don?t add value to a SOP or SWP.
9. API Documentation
API documentation is a technical writing deliverable, containing instructions on how to effectively use and integrate
with an Application Programming Interface (API). It is usually supported by instructions and tutorials to simplify
integration with other APIs such as web-API and software APIs.
10. Service Level Agreements
A Service Level Agreement (SLA) is typically a legally binding agreement between a service provider and a customer,
which outlines the services to be provided and any guarantees, warranties and other mutually negotiated terms between the parties.
11. Media Releases
Media releases are formal documents released by organisations to make official, business-related announcements.
They are typically short and factual documents, which impact organisational stakeholders.
They can also be quite complex and usually require signoff by a senior executive and the marketing and legal departments.
12. Case Studies
Case studies are typically business-specific documents that provide real-world examples of an organisation?s successes.
They are often technical in nature but may have a marketing flavour. They are usually instance-specific documents written
in a passive tone, intended to highlight the benefits of the organisation?s products or services as evidenced by the example case described.
13. Whitepapers
Whitepapers are like case-studies as to utility, but usually focus on specific issues and are written in an active tone.
The authors of whitepapers are usually technical experts, with the professional technical writer?s role limited to ensuring the document's readability.
14. Company Documents
Company documents such as HR policies, procedures, employee handbooks and induction guides require a sound organisational
knowledge as well as technical writing skills. These documents are useful during employees? onboarding phases and provide
them with ongoing guidance and support.
15. Request for Proposal
A Request for Proposal (RFP) or Request for Tender (RFT) is a business document that announces a project and invites
external suppliers or service providers to submit proposals or tenders for the opportunity. RFPs/RFTs are usually written in
both technical and inviting styles and should clearly highlight the project goals, scope of work, and required deliverables.
16. Proposals, Tenders or Bids
Proposals, tenders and bids are typically the reciprocal of RFPs/RFTs, written by a supplier or service provider in response
to RFPs/RFTs released by client organisations. These responses must address all the listed criteria in the source RFP/RFT
including technical and financial requirements, while maintaining a professional yet persuasive tone.
17. Plans
The range of plans organisations might develop is as wide and diverse as the organisations themselves and are too numerous to
try to list, however, strategic, business or marketing plans; emergency management plans and operational plans are a few examples.
Despite their diversity, most technical writers will follow a predictable format, with plans beginning an executive summary,
contents section/index, information chapters or sections and a conclusion or summary.
18. Business Standards
Business standards are documents that define the rules, guidelines, and benchmarks that a business strives to meet in key areas,
such as customer service, quality or operational matters. They can be used during employee onboarding or as references.
The technical writer can document an organisation's business standards, define its values and expected staff behaviours,
which reflect its values and benchmarks.
19. Learning/Training Documents
There is a wide range of learning and training documents which may be developed by learning and development/ training
professionals including instructional designers. These could include learning and assessment strategies, training plans,
learner guides, instructor guides, presentations such as PowerPoint and even videos and other technology dependent artifacts.
These are explored separately under Instructional design, but their authors? skills sets are quite similar to those of most
technical writers, provided they have the necessary learning related qualifications and experience.
|
|
