Posts Tagged ‘ tech writing australia ’

Why do we need technical writers to write technical documentation?

Technical writing is currently a booming industry in India. A professional technical writer is the one who handles technical writing in an organization. Knowledge on industry writing standards and also about the tools that are used to create a more appealing document is necessary for a technical writer. Here in Black & White Tech Writing Solutions we have a team of talented technical writers who possess the knowledge and talent in creating technical document of international standards. We help organizations to provide better user adoption and cut down cost on maintaining a technical support forum.

Technical writing is a process of creating documents on complex technical concepts and instructions in simple steps, so that users can perform intended tasks in a specific way with ease. The process of writing a technical document involves translating technical information into documents that are both precise and concise. There are different types of technical documentations that include release notes, product installation guides, walk through demos; whitepapers and case studies.

The most commonly known technical documents are the user guides and product manuals. Users of any hardware or software products would be aware of these documents.

A technical writer is a professional who possess technical knowledge with good writing abilities. A technical writer should be able to create technical material in a concise and effective way.

For a technical writer to present information in the most appropriate manner, he/she should first be aware of the target audience and the goal of the document. For example, a user manual for java JDK software will require minimum technical information as the audience here would have more technical knowledge when compared to audience for a user manual of a television, which is written for general public.

Documents can be printed or posted online, but before doing that they should follow some similar guidelines, layout and structure in giving information to maintain professionalism in a consistent manner.

A good technical document should follow many formal standards or guidelines. Technical documentation will have various styles and formats to choose from. These are usually chosen depending on the medium it is used and subject area it has to cover.

Generally, technical writers follow formatting conventions described in a standard style guide. The two most used style guides being MSTP (Manual of Style for Technical Publication) and CMS (Chicago Manual of Style). There are also many tools used by technical writers to make a document more appealing and also professional. The tools are necessary to create or customize both text and visual graphics in the document.

Technical writers generally follow five procedures in creation of a technical document. They are:

  1. Analyzing the audience for whom the document is been created.
  2. Collecting all the required information of a product that is been documented.
  3. Coming up with a project plan and a document layout to give a structure for the document.
  4. Proof reading the document created to make sure there are no typographical errors, such as errors in grammar or spelling.
  5. Sending the document for detailed final review from subject matter experts or the technical team.

On acceptance of the document there is a sign-off mail sent by the reviewed team confirming the successful completion of document creation.

Though in some smaller organizations the developers themselves try and create technical documentation, their lack of writing skills are clearly displayed with inconsistent document structure and improper format.

To create a good technical documentation it requires more knowledge about writing format other than just having a good command over language, which a technical writer is trained to possess. Documents that are created with proper documentation knowledge confirm proper use of styles and accuracy in both technicality and writing.

Black & White Tech Writing Solutions Logo

Advertisements

Technical Writing Deliveribles

Technical writing is a broad field that embraces different types of documents used for specific purpose in various fields such as science, construction, engineering, industries, and business. Technical documents are written keeping focus on the type of end-users being targeted.

Types of Deliverables:

User Manual: User manuals are the explanations or instructions written to help end users of the product. Most important property of user manuals is simple language, since it is mostly targeted for non-technical users. Writer’s job is to cover all the minute details of the product and include troubleshooting tricks and clear explanation of difficult technical terms.

Reports: Reports are prepared at all levels for various purposes. Perfect formatting and layout design are very important in a report. Reports require severe research and data analysis. Some types of report include case study reports, business and sales reports and academic project reports.

deliverables

Spec Sheets:  spec sheet is an information sheet that illustrates manufacturing and construction process. Spec sheets are widely used in instrumentation, production and medical industries. Spec sheets are mainly targeted to the service providers or contractors, who will analyze the information and estimate the scope and technology required for the completion of the project.

Abstracts: Abstracts are brief guides of a report that summarizes the whole project or report. Abstracts summarize the important information in the report, and include topics or chapters that are covered in the reports.

logo_bw

Difference between MS Word & Adobe FrameMaker

Technical writers have to produce documents in different formats such as printed, online help, HTML, Electronic publishing, etc. Writers must often publish the same text in several formats. Is there a one-tool solution? Is it possible for technical writers to write once and publish many times? Which tool is the best  Microsoft Word or FrameMaker?

What is MS Word?

Microsoft Word is a word processing program. We all use it to one extent or another in our daily activities. MS word is simple and plain. Word is arguably the best one available in the market. MS word was intended to allow users to write letters, memos, short technical publications, user manuals, and articles, design documents, faxes, and many other documents.

Word vs FrameMaker

What is Adobe FrameMaker?

FrameMaker is a desktop publishing program. When it comes to producing complex, business critical documents for web applications, print, and CD-ROM. MS word is excellent for everyday business application and for shorter documents. FrameMaker has been designed to offer superior benefits for producing long documents.

logo_bw

FrameMaker vs. MS Word: What is the difference?

Functionality

Microsoft Word

Adobe FrameMaker

Managing Document

Word does not handle large document well and begins to have difficulties when it goes over 100 pages. Ideal for creating large documents or books i.e. 200+ pages.

Creating TOC or Index

Compiling the TOC and indexes for multiple files takes much longer in Word than FrameMaker FrameMaker creates TOC and indexes across the whole book.

Formatting

Formatting diagrams and images is awkward and prone to crash the document. FrameMaker has a powerful features such as formatting multiple paragraphs, formatting tables,

Graphics

Word’s performance degrades when graphics files are imported. FrameMaker is the best for document creation that includes large amount of graphics, and graphics layout.

Templates

Creating templates in word is limited, as it is designed for writing letters. We can design separate templates for table and paragraphs in FrameMaker, ensuring consistent format for each type.

Printing

We have to print every chapter in a manual seperately. In word, you can select a range of pages such as 1, 3, 5-9, 11-14. In FrameMaker, you cannot print a discontinious range of pages other than odd or even.

Golden Rules for Technical Documentation

3-13-2013 11-06-54 AM

We have been working on some thoughts about what, how and why we are writing a document. We have come up with few golden rules, which help technical writers to deliver an informative and well-scripted document.

Always keep in mind technical writers Write to inform, not to impress!

Following are some of the golden rules, which each tech writer should follow:

Rule 1: Be Clear

Be clear in your content and think about the real objective of your content. Avoid using phrases and clichés that do not mean anything. Avoid proprietary words that may puzzle the audience and the end-users.

Rule 2: Be Brief

Try to avoid the stuffing contents such as welcome message or overly long instructional text for online forms. Cut your text in half and shorten paragraphs.

Rule 3: Be Creative

Try to be innovative, use a diverse way of representing message, other than paragraphs or texts. Instead of boring paragraphs of text and titles, use billboards, charts, and infographics. These might encourage users to stick with your document.

Step 4: Be Compelling

Know your audience, be excited, be confident, and be bold. Use words that resonate with your audience.

Rule 5: Mind Your Grammar and Spellings

Spellings and grammar distracts users from the message in the content. Always try to implement one idea per paragraph.

Rule 6: Use Templates

Usage of templates enables easier content development, easier gathering of content and makes content consistent.

Pay for quality documentation and your users will be happy. Carefully consider the document formatting, spelling and grammar.

logo_bw

Technical Communication

Technical communication is an extensive field that comprises many form of communications that reveals one or more of the following characteristics:

  • Communicating about technical specifications or any related specialized topics, such as software applications, products, medical events, environmental policy and many more.
  • Interacting by using technology, such as help files, web pages, or any social media sites.
  • Providing tips about how to perform something efficiently, regardless of how technical the task is.
  • User manuals help users be more accurate on their own, improving how easily those products gain recognition into the marketplace and minimizing costs to maintain them.
  • Instructional specifications help one group of experts to communicate efficiently with other technical experts. This result in speeding up development cycles, reducing risks and minimizes rework caused by miscommunications.
  • Training programs present people with new and improved skills, which make them more employable and their organizations and products more capable and safe.

Technical communicators or writers have in common is a user or audience centered approach to provide the particular information, in the correct way, at the specific time to make the end-user’s life easier and more dynamic.

bw

 

Document Development Life Cycle (DDLC)

bw

DDLC is a complete cycle of documentation. It is a structured set of various steps involved in creating any kind of document. To achieve success in the field of documentation, a technical writer should at-least have a conceptual knowledge of DDLC.

Following are the various phases of DDLC:

Requirement Analysis:

Requirement analysis is the first and one of the most important phases of DDLC. In this phase, technical writers analyze the project requirement, tools that will be used in this project, and audience knowledge level. Analysis of project enables technical writers to know about the type and need of the technical document.

Project Designing:

This phase includes the content representation and content collection i.e. how the content should be presented, in which format the document should be presented, how much page should be covered to script the requirements, and so on. Technical writers should make an effort to gain as much as knowledge about the technology and audiences from SMEs (Subject Matter Experts) and Internet. A good bunch of information helps a technical writer to prepare an information rich document.

Developing the content:

In this DDLC phase, the actual content is scripted on the basis of project designing and planning. Graphics and illustration are prepared in this phase.

Editing or Proof Reading:

In this phase, the document is thoroughly checked for consistency and errors such as spelling and grammatical errors.

Publishing:

Parent authority publishes documents created by tech writers. Generally, tech documents are published either in hard copies or in digital formats. Several publications options can be used based on the client’s requirement.

Maintenance:

In this phase, a backup of the document is taken for the future use. It also includes collection of further updates and modification of the document.

bw