Technical Writing and Documentation

7/31/2019 Technical Writing and Documentation

1/43

TECHNICAL WRITING AND DOCUMENTATION

2 MARKS

1. NAME THE WRITING STRATEGIES?

LOCATING:

The presentation of the information should be such that it should allow readers to scan the

information selectively, in a glance. Tables and lists must be used where required.

GROUPING:

Organize and then group the pieces of information in chunks so that it is easy to find. The

process of grouping informations (chunks) in a structured and sequential manner so that the

users can easily locate, understand and use it is known as grouping or chunking.

e.g.: you may be trying to remember something, say mobile number, 9860408487

It is easy to remember if you group them as 98-60-40-84-87

LABELLING:

Label each group of information approximately. The heading should accurately tell readers

what the section is about. This means giving approximate title names to the sections and

subsections.

RELEVANCE:

Identify important and valid information. Use special notices or different font so that the

readers can confidently skip parts of the document that does not appeal to them to go straight

to the important part of the document.

Using different font sizes and types helps readers to locate the information they need.

Warning, notes, tips etc. should stand out. Similarly GUI items, commands etc. should be

written I different font types so that they can be easily identified in a large paragraph.


2/43

MODULAR:

It is important to update and maintain the information in documents to ensure their

continuing effectiveness. However, updating and revising documents is time consuming and

expensive. Because of the modular structure, discrete units of information can easily be

deleted or replaced with minimal disruption to the rest of the document.

CONSISTENCY:

The terminology, the punctuation rules, the format and the style should be consistent

throughout the document.

TRANSITION:

Transitions alert readers of the changes within the writing and the readers are prepared for

the flow of ideas. Effective transitions logically connect paragraphs with one another. This

way, readers are not caught off guard by the upcoming details.

2.WHAT IS POST MORTEM IN TECHNICAL WRITING?

The process of looking back at a completed project's design and its development process,in order to identify those aspects where improvements can be made in future projects

Post-mortems enable individual learning to be converted into team and organizationallearning.

It is also defined as critical examination, evaluation or assessment of someone orsomething past.

3. DEFINE INDEXING AND ITS USES.

It is a systematic arrangement of entries created and designed to enable the readers locateinformation in the document. An organized and thoughtful index ensures that the contents

of your document are accessible and also increases its value.

Indexing is a complex decision process involving a right mixture of art, judgement,choice of words, intelligence and writing.


3/43

The purpose of indexing are: Allows users to refer to the secondary topics not mentioned in the chapter headings. Distinguishes valid and important information from that of passing mention. Provides subentries to guide directly to a specific aspect of a topic.

4. WHAT IS WRITERS BLOCK?

Writing from the scratch can make people anxious and apprehensive. Even the of thewriters experience a time when they cant seem to get on with their writing.

In a situation, following the style guides, the writing guidelines, and all possiblechecklists will also not help. This phenomenon involving temporary loss of ability to

begin or continue writing is called the writers block.

5. WHAT IS OUTLINING?

An outline is a general plan of the material that is to be presented in a speech or a paper.The outline shows the order of the various topics, the relative importance of each, and the

relationship between the various parts. A summary of a subject, consisting of a systematic

listing of its most important points.

Before you start writing, develop an outline of the contents of the document, which willhelp you develop a structure for your document. After creating and outline of the of the

document you are working on , first get it reviewed by the approved people.

6. WHAT ARE THE 3 ISSUES CREATED BY BAD DOCUMENTS?

1. Incomplete information and errors in the document mislead the customers about thecapabilities of the product. This can lead to customer dissatisfaction and frequent support

calls.


4/43

2. Inaccurate, incomplete and outdated documentation can negatively affect the customerswhen they resolve issues by referring the documentation. It increases the learning curve

of the user and also increases the support costs.

3. Inaccessible information annoys the user, especially when they are trying to get some taskdone. This happens when navigation tools like TOC and index does not help to locate the

information.

7. WHAT IS FORMAL EDITING?

This edit ensures that the document conforms to the organizational standards regarding

layout and format. It also looks at the general format of the document to ensure that the text

and artwork confirm to visual requirements. During a format edit, the editor checks the

following:

General format of the document Appropriate use of font for the inline text and the line thickness in the illustrations

Accuracy of the mathematical equations Use of appropriate special symbols

8. WHY AUDIENCE ANALYSIS IS NEEDED FOR TECHNICAL WRITING?

The audience are the users who will be using the product and reading your writing. How you

write and what you write basically depends on your audience. You have to analyze them to

know about their requirements and how you can give it to them. Knowing your audience will

help you understand them better and will help you determine the following:

The knowledge they have about the subject discussed in the document The terminology you should use. How simple or complex your writing needs to be. The tone you will have to use when you write. Tone, in writing, refers to how

something is explained.


5/43

9. WHO DOES INDEXING? WHAT ARE THE ACTIVITIES INVOLVED?

A person who does indexing professionally is called an indexer. An indexer is ideally a

person who has studied indexing and has a good understanding of creating a good index.

The activities involved are:

Look at TOC Read the document Understand terminology Create index entries that are meaningful to audience Keywords Synonyms Check Edit and Review

10. WHAT IS FORMAL REVIEW?

It ensures the technical accuracy and completeness of the information. It is also called

technical review.

11. LIST GUIDELINES FOR EFFECTIVE WRITING?

1. Work from an Outline2. Complete areas for which you have information3. Create a glossary4. First write and then get it right5.

Insert place holders

6. Deal with problems later12. WHAT IS THE SCOPE OF TECHNICAL WRITING ACTIVITIES?

1. Technical editors2. Web writers3. Indexers4. Marketing writers5. Medical writers


6/43

6. Proposal writers7. Resume writers13. WHAT IS STC?

STC stands for society for technical communication. The mission of the STC is to improve

the quality and effectiveness of technical communication for audiences worldwide. It

includes:

Technical writers Editors Graphic designers Multimedia artists Information designers Translators and others whose work involves making technical information

understandable and available to those who need it.

14. NAME ANY 5 COMPONENTS OF WRITING SKILLS.

1. Writing your thoughts clearly and concisely2. Understanding and expressing what the readers need to know.3. Finalizing the style, format and templates.4.

Deciding the flow of informationorganizing and structuring information

5. Expressing clearly the knowledge, ideas and concepts to the users.15. NAME ANY 5 PERSONAL TRAITS NEEDED FOR TECHNICAL WRITING

CAREER?

1. Communication2. Avoid Assumptions3. Continuous learning4. Be a student and a teacher5. Curiosity about details6. Team spirit7. Focus8. Responsibility9. Reasoning and problem solving10.Handling Pressure11.Positive attitude12.Handling stress


7/43

16. GIVE 5 USES OF TECHNICAL DOCUMENTS.

17. LIST MAJOR SDLC METHODS.

Waterfall Spiral, RUP VDM, B Method RAISE etc.

18. WHAT IS TECHNICAL WRITING AS PER MARKEL?

Technical writing conveys specific information about a technical subject to a specific

audience for a specific purpose.

19. LIST SOME MARKETING TECHNICAL DOCUMENTS

Datasheets Brochures Success stories White papers Promotional Materials Newsletters

20. DISCUSS THE TERM SME?

A subject-matter expert (SME) or domain expert is a person who is an expert in aparticular area or topic.

A Subject Matter Expert is an individual who understands a business process or area wellenough to answer questions from people in other groups who are trying to help.

It is most commonly used to describe the people who explain the current process to ITand then answer their questions as they try to build a technology system to automate or

streamline the process.


8/43

21. WHY DO WE NEED DEVELOPMENT METHODOLOGIES? - IMPORTANCE

OF PROCEDURES?

Manuals have a bad reputation, often for good reason. The good documents dont get the

credit they deserve because the bad one gets all the attention. The worst part is that writers

get the blame, even when they are given inadequate time, tools and support to do the job.

22. WHAT ARE THE KINDS OF TECHNICAL WRITING?

Technical editors Web writers Indexers

Marketing writers Medical writers Proposal writers Resume writers

23. WRITE A NOTE ON STC.

The Society for Technical Communication (STC) is a professional society for theadvancement of the theory and practice of technical communication.

Headquartered in Fairfax, Virginia, USA, STC is the largest organization of its type in theworld according to its website. It includes 108 chapters, 22 special interest groups (SIGs),

and about 7,000 members worldwide. STC members work in a wide range of roles,

including:

Technical writing Editing Consulting Content development Education Environmental, safety, and health communication Graphic arts Human factors Indexing Information architecture Instructional design Management Technical illustration


9/43

Most STC members belong to one or more communities, which are either geographicchapters or special interest groups (SIGs). Most chapters are in the United States, but STC

includes members from 14 countries. The largest group outside the U.S. is the chapter in

Toronto, Ontario, Canada.

STC publishes a quarterly journal, Technical Communication, and a monthly magazine,Intercom.

24. WHAT IS THE NEED OF ORGANISING IN WRITING?

Makes the writing process

Simpler quicker and much more effective

25. NAME THE KEY COMPONENTS OF A BOOK

Front and back matter Table of contents Preface Chapters Footnotes and Endnotes Appendices Glossary Bibliography Index

26. GIVE 5 TRAITS OF TECHNICAL WRITERS.

1. Communication2. Avoid Assumptions3. Continuous learning4. Be a student and a teacher5. Curiosity about details6. Team spirit7. Focus8. Responsibility


10/43

9. Reasoning and problem solving10.Handling Pressure11.Positive attitude12.Handling stress

27. NAME THE DIFFERENCES BETWEEN FOOT NOTE AND END NOTES

Sometimes, an asterisk or a superscript number appears against a phrase or sentence in apiece of text, referring to a corresponding note.

When these notes appear in their own section at the end of a chapter (or sometimes theend of a whole book), they are called endnotes. Notes at the bottom (foot) of the page are

called footnotes.

Heres an example of what footnotes look like (notice theyre on the same page as the textto which they refer).

And heres an example of what endnotes look like (notice theyre on a separate page fromthe text to which they refer).

Footnotes. The pros: You can quickly check the note without leaving the page, and theauthor can stuff funny things in there. The cons: its distracting if there are lots of notes

and can be visually ugly.

End-notes: The pros: Saves research questions to the end and keeps pages clean. Cons:the footnotes are rarely read and if they are, its hard to know what the author is referring

to. You also have to jump back and guess where the note came from.

28. HOW DOCUMENTATION IS USED?

For quick help For information To read at leisure

29. LIST SOME MAJOR TYPES OF TECHNICAL DOCUMENTS


11/43

30. WHAT IS AN ONLINE DOCUMENTATION? GIVE 2 EXAMPLES

Online documentation can be just about any information that is stored and viewed inelectronic form including, Windows Help files, electronic books and manuals, context-

sensitive help screens, databases, document management systems, and many more.

Online documentation:

Is not portable Requires additional up-front planning and design May not let the user view both the system and the documentation effectively May not be accepted by users Must not include installation instructions, therefore, at least some paper is still

required

Is not practical for some environments, for example where PCs are not availableEG: Online help, online tutorials, Product Wikis, UseNets, Manpages (UNIX)

31. WHY DO WE NEED WHITE SPACES IN DOCUMENTS?

White space refers to the portion of a page that are blank, no matter what color orbackground or paper you are using. Each page of a document should be pleasing to the

eye.

In deciding your layout, you must ensure that you leave sufficient white spaces. Goodcontrol over white spaces can improve the look and feel of the text.

32. WHAT SHOULD BE CAPITALISED

Software, operating systems and product names as appropriateE.g.: UNIX, Power Point, and AutoCAD

Menu names and dialog box title


12/43

Key names, combinations and sequences (preferably)E.g.: CTRL, SHIFT, CTRL+ALT+DEL

The first word of a list item if the item is a complete sentence or ends with a period.33. WHAT ARE WIDOWS AND ORPHANS IN WRITING?

Orphan is the single word appearing at the bottom of a paragraph, or column, or page. Widow is a single word or short phrase that appears at the top of a column or a page. Orphans and widows interfere with eye movement from one line of text to the next text

and also adds unnecessary white space. So try to avoid Orphan and Widow

10 MARKS

34. PROBLEMS IN DOCUMENTATION BY NON-WRITERS

1.NOT COMMUNICATING WHAT IS REQUIRED:

Communication skills are not about just about grammar or writing skills. As a technicalwriter your thoughts should be presented in such a way that a person you are

communicating to, easily understands what you want them to understand. The most

common problems that usually arise in the documents written by non-trained writers.

2. THINKING LIKE THE CREATORS OF THE PRODUCT:

They usually think that people want to know how technology works. Since theythemselves have the in-built curiosity or urge to learn the internal operations of the

products, they believe that users may want similar information.

The engineers know the application too well and are likely to provide technology centricinformation. This happens because it is probably impossible for them to step back and

look at the product from the user point of view.


13/43

3. MAKING ASSUMPTIONS:

The SME know the product inside out. They are very comfortable with the jargon,assumptions, work arounds, shortcuts and troubleshooting methods. Hence they make

logical assumptions that are not understood by non-experts. They miss the obvious,

forgetting that the users do not perceive the obvious.

Writers are not experts and hence they are likely to make the same mistakes andassumptions as the users. they also ask the same dumb questions that the novice users

may sometimes ask. Hence, the writers can translate those information into

troubleshooting tips, warnings, notes etc. these dumb questions turn out to be useful

information in the document.


14/43


15/43

35. DISCUSS THE ESSENTIAL SKILLS OF TECHNICAL WRITING.

ESSENTIAL SKILLS OF A TECHNICAL WRITER

Technical Writers obtain and present specialized information within strict accuracy andformat requirements and strong organizational skills. Technical Writers use the following

skills, knowledge, and abilities to accomplish their daily tasks of technical

documentation:

Communication: Communication may be of following types: Written - Communicating effectively in the form of technical writing as dictated by the

needs of the audience.

Verbal - A technical writer must have the ability to interact well with SMEs and clients.This helps in getting relevant information from them in a professional and personable

manner. Conducting in-depth interviews with subject matter experts helps in

understanding the product or procedure. Excellent verbal communication helps technical

writers to convey information by talking effectively.

Active Listening - Listening actively to other people and asking appropriate questions. Analyzing- Capability to analyze the needs of the target audience. Strong Concentration-Technical Writing requires the ability to concentrate for long

periods of time.

Information Gathering Skills - Knowing various sources of information and identifyingessential information.

Strong Organization Skills- Organize multiple pieces of information, so that the need forfurther information is recognized and redundant or irrelevant information is discarded.

Continuous Learning - Keeping abreast of new information, material, recent advancesand technology.

Technical AttitudeInterpreting complex technical material Giving and Taking Constructive Criticism: Technical writers should welcome useful

criticism, which should be analyzed and taken forward for reworking their original ideas

until the satisfaction of the customer or user.

English LanguageA good grasp of grammar, composition, structure and content of theEnglish language including the meaning and spelling of words is essential for doing

justice to the technical writing profession.

OR


16/43


17/43

36. DISCUSS BASIC SKILLS FOR TECHNICAL WRITERS.

37. DISCUSS PROS AND CONS OF PROCEDURES


18/43


19/43


20/43

38. WHAT ARE THE ELEMENTS OF PLANNING?

39. DISCUSS TYPES OF INFORMATION


21/43


22/43

40. DISCUSS GENERIC REVIEW PROCESS


23/43


24/43

41. DISCUSS ON THE ISSUES IN TECHNICAL WRITERS JOB AND WHAT CAN

BE DONE FOR THE ISSUES.


25/43


26/43


27/43

42. DISCUSS ABOUT TEAM SPIRIT AND WHAT NEEDS TO BE DONE FOR THE

SAME.


28/43


29/43


30/43


31/43

43. DISCUSS ON THE COMPONENTS OF REQUIREMENTS CHECKLIST


32/43


33/43

44. DISCUSS ABOUT WRITERS CHECKLIST COMPONENTS.

REFER PAGE NO: 470

45. DIFFERENTIATE TECHNICAL AND CREATIVE WRITING


34/43

46. DISCUSS THE TECHNICAL WRITING MYTHS

REFER PAGE NO: 26

47. DISCUSS DDLC.

1. Planning2. Organizing3. Writing4. Editing5. ReviewingREFER PAGE NO: 88

48. MAP DDLC TO SDLC AND DISCUSS THE STEPS

PAGE NO: 103

49. DISCUSS HOW TO ORGANISE FOR WRITING.

1. CREATING THE FRAMEWORK2. DEVELOPING OUTLINE OF THE CONTENTS3. GROUPING THE INFORMATION4. PRESENTING THE INFORMATION5. DEVELOPING THE FUNCTIONAL FLOW.

REFER PAGE NO.: 300

50. DISCUSS THE GUIDELINES FOR WRITING HEADINGS

REFER PAGE NO.: 309

62. COMPARE DDLC TO SDLC AND DISCUSS

REFER PAGE NO.: 103

63. DISCUSS HOW TO ORGANIZE FOR WRITING

SEE QUESTION NO.: 49 OR REFER PAGE NO.: 300 in book


35/43

51. DISCUSS THE ADVANTAGES AND DISADVANTAGES OF STARTING A

DOCUMENTATION COMPANY


36/43

52. ADVANTAGES AND DISADVANTAGES OF ONLINE VS PRINTED

PUBLISHING


37/43


38/43

53. DISCUSS THE TIPS AND GUIDELINES FOR WRITING RESUMES

REFER PAGE NO.: 376

54. ELABORATE THE ANALYSIS PHASE OF A DOCUMENTATION PROJECT

1. Platform2. Product / Build Version3. Documentation format4. Documentation tool5. Standards and conventions6. Documentation Delivery7. Product Training8. Information Gathering9. SMEs and Reviewers10.Important Dates and Deadlines

REFER PAGE NO.: 117

55. DISCUSS COMPONENTS OF A DOCUMENTATION PLAN


39/43


40/43

56. DISCUSS ON MANAGERIAL SKILLS FOR TECHNICAL WRITING

REFER PAGE NO: 62

57. DISCUSS THE PERSONAL TRAITS FOR TECHNICAL WRITING

REFER PAGE NO: 50

58. DISCUSS THE ANALYSIS STEP OF DDLC

REFER PAGE NO.: 117


41/43

59. CONTENTS OF A DOCUMENTATION PLAN


42/43

60. TASKS, RESPONSIBILITY, SKILLS & EXPERTISE CHART


43/43

61. PROCEDURES/MANUALS GUIDELINES

Documents

Technical Writing and Documentation