Rise of the DITA tools

You can now read this article at this new location on techitive.com: 
http://techitive.com/trends/rise_dita_tools.php
You can find this and many more articles related to technical documentation by Chakravarthy Tenneti and other writers on the website - techitive.com.

Industry and People Trends in Technical Documentation

You can now read this article at this new location on techitive.com: 
Industry Trends - http://techitive.com/trends/industrytrends.php
People Trends - http://techitive.com/trends/peopletrends.php
You can find this and many more articles related to technical documentation by Chakravarthy Tenneti and other writers on the website - techitive.com.

Tools Trends in Technical Documentation

Technical writers have taken a big leap from mere word processing and desktop publishing tools to structured authoring tools that make use of XML and other latest technologies.

XML
Extensible Markup Language (XML) opens a many exciting new opportunities for technical communication, such as improving consistency, reusing content, moving toward structured writing, and reducing publishing costs.

The advantages of using XML for documentation include:

1. Enforcing consistent organization


2. Automating and enforcing formatting


3. Using metadata for versioning


4. Supporting content reuse and exchange


5. Reducing localization costs, and


6. Simplifying database publishing

XML helps in creating custom markup languages. It is extensible in the sense that it allows users to define their own elements and help information systems share structured data. It is vendor-neutral and can be customized for any specific requirements.

Structured FrameMaker
Using the advantageous SGML and XML concepts, Structured FrameMaker helps in achieving consistency in documentation. It uses Element Definition Document (EDD), which is a FrameMaker-specific DTD (Document Type Definition). Its features are similar to XML and DTD and are more tuned toward technical documentation in complex industries where deliverables must be generated in different models for the same product. The intuitive tree-like structure helps the writers view and define the conditions and contexts as derived from the grammar of the EDD. The emergence of Structured FrameMaker signifies the shift from style-based, paragraph-oriented word processing and publishing to structured authoring. Structured documents have hierarchical relationships among the various document components.

DITA
With an aim to exploit XML as its encoding format, a workgroup was formed in late 1999 to develop the architecture of an alternative XML-based documentation system. The workgroup placed this architecture on IBM's developerWorks web site. Thus began a revolution in technical communication called DITA (Darwin Information Typing Architecture).

According to IBM's developerWorks
"The Darwin Information Typing Architecture (DITA) is an XML-based, end-to-end architecture for authoring, producing, and delivering technical information. This architecture consists of a set of design principles for creating "information-typed" modules at a topic level and for using that content in delivery modes such as online help and product support portals on the Web."

DITA soon became world-famous with its array of features such as topic orientation, content reuse, specialization, property-based processing, and the advantage of leveraging existing popular language subsets. DITA also brings the benefits of object-oriented model such as encapsulation, polymorphism, and message passing. DITA takes you from the book-oriented documentation methodologies to content development in the form of modular topics. You can reuse these topics in different kinds of deliverables. You also have the advantage of adding new elements through specialization, wherein you can use the base DITA elements and adapt them to your requirements.

Content Management Systems
Content management systems and version management systems have come of age and become a part and parcel of the documentation process. With XML and DITA trends setting in, the content management is an essential part of the entire documentation process and not just an auxiliary support system. The content management is developed exactly to suit the needs of technical documentation teams.

Other Tools
Other tools such as XMetal, EasyDITA, DITAToo, SyncroSoft oXygen, and ArborText Epic Editor are gaining significance owing to the emergence of DITA as the future of technical communication. DITA Content Management Systems such as Astoria On Demand, Author-it, Bluestream XDocs, DITA Exchange, DocZone, SiberLogic SiberSafe are among the significant players. DITA Storm is the online DITA editor that runs entirely on JavaScript and can be used on any internet browser.

Process Trends in Technical Communication

An increasing focus on quality and an attempt to arrive at universal standards for quality and processes are some of the significant trends that are worth noticeable in technical writing.

Documentation Development Life Cycle
The traditional documentation development life cycle of pre-writing, research, writing, reviewing, editing, and publishing is going through many significant changes. However, most changes pertain to the industry and the product or service that is covered. Simply put, the most significant transformation is that the documentation development life cycle is now customized to each industry, product or service area, and other factors to aid in an effective productivity cycle.

Information Process Maturity Model
While Capability Maturity Model (CMM) and CMMi (Integration) levels are used to determine the efficiency of software development processes, technical writing also has its own variants of Process Maturity Models that set standards for various technical documentation organizations. JoAnn T.Hackos, in her book "Managing Your Documentation Projects", proposes a process maturity model as applied to documentation process. According to this model, there are six levels of process maturity for any information development organization:

• Level 0: Oblivious. Lacking proper standards and practices in place, anyone can write in such an organization. Without a proper definition of roles and responsibilities for the writers, quality is not focused in such an organization.


• Level 1: Ad Hoc. Even though style standards are not enforced, writers and trainers manage their own work. With extreme difficulty, they try to standardize the processes followed by all the writers.


• Level 2: Rudimentary. These organizations herald the beginning of style standards and process standards. However, standards are abandoned when the going gets tough.


• Level 3: Organized and Repeatable. The focus shifts from mere managing of projects and following processes to introduction of new processes. More time is available for improvement of the existing standards and processes.


• Level 4: Managed and Sustainable. With a continuous focus on following and improving the processes, innovation is closely linked to customer needs. Bureaucracy is defeated and time is dedicated for quality.


• Level 5: Optimizing. With strong quality measurements in place, these organizations focus on continuous improvement and innovations become a part of the process with constant focus on enhancing the customer experience.

More and more organizations are trying to figure their place in the Information Process Maturity Model and moving towards improving their processes to reach the optimizing level.

Trends in Technical Writing

The Information Technology industry is abuzz with information flow that Technical Communication is one of the most promising professions. Yet, most people are hardly aware of what is actually happening in technical writing. This article tries to explain the trends in technical writing. It does not explain in detail the emerging technical writing concepts or industry standards. It tries to explain in brief the plight of technical communication as a profession and the nuances associated with the changing trends in this profession.

Broadly speaking, the trends can be either related to the process, tools, or industry changes. This article, thus, demarcates the trends according to this broad classification and provides a clear understanding of the emerging trends in each area. You will understand the influence of emerging tools and technologies such as XML, DITA, and other applications. You can get a clear view of the industry trends associated with the emergence of Web 2.0 as the next force to reckon with on the Internet area. Likewise, you will gain a clear understanding of the people trends in this profession. Indeed, every industry and profession has its own share of evolution and trends.

Technical writing has been on a continuous evolving mode since the first time a scientist started documenting his experiments. However, the recent trends in technical writing signify a dramatic shift toward better user experience akin to the software development and production processes. These trends can be broadly classified into the following areas:

1. Process trends


2. Tools trends


3. Industry trends


4. People trends

Scaling new heights as a technical writer

“Tech Writers are puzzle-solvers. They ask lots of questions. My one-liner, when asked what really do I do, is “translate from English to English”.
- Matt, Internet.

A developer needs to learn more languages and master more coding principles. A test engineer needs to learn more testing tools and master new logic. What should a technical writer (or editor) do to grow? Some argue that it is the organization's responsibility to make sure that the technical writers’ skills are updated. However, the truth remains that the writer (or editor) must initiate self-development in all the necessary spheres. Being a technical writer, if you are really interested, here are some simple ways in which you can grow and move up in the field of technical communication.

Language

• Upgrade your linguistic abilities continuously. Love or loathe it, you must keep honing your linguistic abilities to stay and grow in the field of technical communication. Remember that you need not become a Shakespeare, but you must strive to convey your message accurately to all levels of your audience.
• Merge language and technology in your learning process. If you find it difficult to follow the ‘learn one-word-every-day’ principle, read modern literature in both technical and non-technical journals to find new words, idioms, phrases, and their usages. Visit any of the journals’ websites and access the PDF versions to read them when you have the time. Thus, you hone your language skills while knowing about a technology if you go through some technical journals.

Tools

• Be aware of all the new and old tools that are being used. You need not know the in-depth functionality of all tools. Make it a point to know the purpose of the various tools and their basic features.
• Upgrade your tools knowledge too, regularly. If you are well-versed with Microsoft Word, try to learn about Adobe FrameMaker. If you are good at FrameMaker too, try to learn technology such as XML and DITA. From writing to structured writing to collaborative authoring, new methods and tools are flooding the market for you to implement. Try them and learn the basics. Most of the product companies offer trial versions for you to conduct a test ride on the tool. Consult your senior writers to know more about the current trends and new tools and technologies.
• Make use of open source applications. Ask your seniors or online experts about some good applications and try these open source tools.

Domain

• Master your domain and begin exploring other domains. Try to establish the relationship between these domains to broaden your perspective on all the domains.
• Probe further into your current domain and know about similar and different products. If you are in the networking domain, learn more about switches of different types, and then expand your knowledge base into routers even though you are not currently working on them.
• Begin knowing the basics of a couple of other domains. The Internet is the best place to conduct your research and learn more about the domain. As you do not regularly work on this domain, it would be useful to collate and store all information pertaining to it. You can revisit this information periodically to retain your knowledge base.

Processes

• Learn more about the different processes involved in the technical communication arena. You can master tools and domains within a stipulated amount of time. However, you can master the processes only through experience. Processes tend to evolve at different rates. Experiment, explore, and share your process experience.
• Keep a track of technical documentation trends. Visit some technical writing communities online to gather some of the common trends or read the blogs of experienced technical writers across the globe.

Project Management

• Understand the nuances of project management. Sooner or later, you are expected to manage people and coordinate their work. You must learn principles such as - Different strokes for different folks - to play the management role efficiently.
• Identify the relation between project execution, process frameworks, and people management. There are many underlying principles that you need to understand and appreciate to become and grow as a manager.

Collaboration

• Team up with other writers in various activities and participate in discussions pertaining to the technical communication field.
  Exchange your best practices frequently with colleagues across teams and locations. Thus, you get a chance to share and learn at the same time. In fact, this is one of the easiest ways in which you can move up along with others.
• Share your knowledge with others through various methods – write an article for your company newsletter or a blog on the internet. Send an email to the different technical writing groups to discuss, share, and learn new things.

You must have realized that it is time to stop cribbing about the lack of prospects to learn new tools in your current project. If development is your goal, you can achieve it easily by moving in the right direction. Note that these tips are not specific to writers and editors. Anybody who is working in any type of technical communication project can benefit by following the aforesaid ideas.

Research Methods in Technical Documentation

You can now read this article at this new location on techitive.com: 
http://techitive.com/process/research_methods.php 
You can find this and many more articles related to technical documentation by Chakravarthy Tenneti and other writers on the website - techitive.com.

Document Development Life Cycle

Technical documentation happens simultaneously with the software development and hence has a life cycle similar to the software development life cycle. You need to follow all the stages in this life cycle to ensure that the documents are technically accurate and are of good quality. The six steps of the document development life cycle are as follows:

Preparation
This is similar to the requirements gathering phase of the software development life cycle. Gather all the requirements and available resources during this stage of the life cycle. Identifying the requirements includes establishing the primary purpose of the documentation exercise, analyzing the audience of the documentation, and defining the context and scope of the documentation.

The advances in the field of technical communication also prompted the necessity of identifying the medium. Earlier, hard-copy help manuals were the only source of information provided to the end user. Now, help is available in various formats - online Help, PDFs, and printed documentation. Thus, it is necessary to identify the medium at this stage.

Research
This stage involves reading the source documents such as system specifications and functional specifications. Gather the required inputs from the subject matter experts using various modes of communication such as interviews and emails. Analyze the information received from different sources such as source documents and SMEs during this stage.

You must also understand the importance of secondary research activities - brainstorming, mind mapping, and information mapping. Depending on the audience analysis and audience profiling conducted during the preparation stage, you might have to conduct these secondary research activities to collect additional information. Then, you should be able to define an outline of the document. Such an outline lays the foundation of a technically accurate user-friendly document.

Organization
Every formal document needs to be organized to suit to the end user needs. Organize your information using existing document references, customer-specific style guides, information mapping principles and structured documentation concepts. You must organize your document considering the type of the document - proposals, marketing collaterals, white papers, articles, manuals, or online help. The content in the manuals can again be classified based on the information needs - user manual, installation manuals, training manuals, tutorials, service manuals, operations' manuals, and special-purpose manuals.

You must also focus on visual organization - layout and design, and typography. Choosing appropriate visuals help in a variety of ways such as - showing objects and spatial relationships, displaying geographic information, and showing numerical relationships.

Writing
This is akin to the software coding stage. Writing is an essential part of DDLC. The quality of the document depends on the writing style and the flow of the content. Prepare a documentation plan before embarking on the journey of writing. Use all the information and resources gathered during the previous phases to write accurately.

The two major aspects of writing that you must consider include perspective and usage and process. Choosing the right perspective is also very important while presenting the information. Perspective refers to the approach towards the task on hand. It also refers to the understanding of the context of the document and writing accordingly. Usage and process refer to the usage of words and the process used in writing. You need to consider various aspects such as the usage of American and British English, style guides, and the appropriate method of development.

Review
Begin the review stage by verifying and revising your own draft. You must check your draft for completeness, accuracy, and consistency during this stage along with a check for the Grammar guidelines and usage principles. You must send your document for a peer review. When you peer-review, you not only check the Grammar and style aspects, but also judge the quality of the document by keeping in mind the information needs of the end user.

Editing and proofreading together form an integral part of the review process. Editing is a formal process defined with set goals to improve the overall quality of the document and ensure that the document is technically accurate.

Delivery
As discussed in the Preparation stage earlier, the document must be delivered in a format that is accessible to the end user. You might have to deliver the same installation guide in two different formats for two different types of audiences. Most often, every software application is delivered along with an Online Help and printed documentation. Hence, it is necessary to identify the accessibility needs of the end user and deliver the documents accordingly.

Technical writing and copywriting

Without discussing the common differences between the two similar writing fields, I would like to bring upon a few interesting observations I had while going through a good book on copywriting.

Features and benefits
While copywriters are expected to focus on benefits and then enumerate the features, a technical writer must explain the features and then enlist their benefits. More often than not, in user documentation, the user must already be aware of the benefits and would like to know how to use the product to get these benefits. However, the audience of the copywriter would like to know the benefits for using the product so that they can decide whether or not to buy the product. The ability of the copywriter lies in the ease with which the audience is persuaded or convinced to buy the product. The ability of the technical writer lies in the ease with which the audience is able to use the product without getting lost.

Call for action
While a copy calls for the action of buying, the end user documents call for ease of use. Though it is cliched, I'd like to recollect the old marketing saying that the customer is the queen. However, it is difficult for the copywriter to satisfy the customer. The technical writer just needs to help the queen effectively utilize the product and satisfy further. The catch here is that the mantra behind communication for both these fields of writing is to be simple. While there are some complex advertisement copies everywhere, these are very simple to their audience.

This brings us back to the 'audience' part of both forms of communication. Unlike poetry or writing novels, both copywriting and technical writing are directed by the audience and not by their creativity.

Understanding the Technology Adoption Life Cycle

Audience analysis does not always yield the desired result of understanding the exact needs of the audience. Such an analysis is very helpful when you develop content for a new product that introduces a new technology. As the technology becomes well-known and the product comes up with enhanced versions, it is necessary to understand more about the changing needs of the audience. Technology Adoption Life Cycle plays a prominent role in such a situation. A technical writer must understand the nuances of the technology adoption life cycle to cater to the needs of the audience effectively.

The technology adoption lifecycle is a sociological model, originally developed by Joe M. Bohlen and George M. Beal in 1957 at Iowa State College. Its purpose was to track the purchase patterns of hybrid seed corn by farmers. Approximately six years later, Everett Rogers broadened the use of this model in his book, Diffusion of Innovations. In the book, Crossing the Chasm, Geoffrey Moore proposes a variation of the original lifecycle. He suggests that for discontinuous or disruptive innovations, there is a gap or chasm between the first two adopter groups (innovators/early adopters), and the early majority. (Source: Wikipedia.com)

Broadly speaking, documentation managers must position information development to match the needs of the technology adoption life cycle. Likewise, funding for information development must focus on the needs of the majority market. Technical writers must understand the participants in the Technology Adoption Life Cycle before getting into the documentation tasks.
In the technology adoption life cycle, customers can be classified into these categories:

• Innovators are technical experts who need little information to begin with. In most cases, innovators help in the development of the product and assist in documenting use cases and improving functional specifications. You can gather information from the product developers and organize it to meet the needs of the innovators without simplifying the content to a great extent.
• Early adopters require a subset of information products as they are more likely to learn things by experimentation. Most of the times, they have access to the product developers and product developers see them as seasoned technical professionals. Early adopters use the inputs of the product developers to understand how they need to implement in their environment.
• The Chasm – Moore points out that most companies find it difficult to cross this chasm as they focus too much on the innovators and early adopters. They fail to cater to the needs of the majority of customers and their solutions are not so successful.
• Early majority customers are better known as pragmatists demanding good service, information, and training to try the product. As Moore points out, they rely more on the whole product that comes bundled with more information, better training resources and adequate technical support. They prefer elaborate procedures with clear instructions and are reluctant to accept vague information.
• Late majority customers are skeptical about new products and resent complex new technologies to a considerable extent. They need quick and easy answers to their questions about using the product. They need simple yet clear procedures to implement their tasks. They are disinclined to get in touch with the customer service because they assume that the support personnel are not aware of their business needs and concerns. Most of these customers ask for job aids, wizards, performance support, and maintenance support aids.

While innovators and early adopters help in the introduction and development of product, it is only the early and late majority customers who drive the growth of revenue for the product. The customers in these groups encompass the largest customer base. Technical writers should understand where the product stands along the bell curve and tune their documentation to suit the needs of the corresponding customers.

Ref:

Managing your Documentation Projects - JoAnn T.Hackos

Wikipedia.com

Common mistakes Technical Writers commit

To err is human, to forgive is divine. The problem lies in the fact that users are also human and they are not used to forgiving – especially people like product designers, developers, and writers. This can be attributed to the variety of choice available to the users. They can happily switch to another product if a particular product fails in any aspect. A user might also be dissatisfied if the product is very good but lacks meaningful help information to use it comfortably.

Here is a list of some common mistakes that technical writers often commit. Instead of relating to the grammatical, syntactical and style mistakes associated with writing, this list focuses on the roles and responsibilities of a technical writer. It is broadly classified relating to the three major actors – subject matter experts, users, and writers – who play a significant role in the development of an effective Help system.

Mistakes with regard to subject matter experts

• Waiting to hear from the developers. Technical writers need to be proactive and try to gather information from the various subject matter experts. It is very fortunate if the software development process includes documentation as a significant part and there is a separate deadline for submitting the different drafts of documentation during the different stages of product development. Yet, it is the responsibility of the technical writer to step forward and fix an appointment with the Project Manager and seek permission to interact with the product designers and developers.
• Not planning the interaction with the developers. Technical writers and developers are often at loggerheads when a deadline is due and a new feature is added to the product. The developer has to complete the assignment within time and the technical writer has to gather as much information as possible within the short period of time. None of them can compromise on the quality of work that they do at this juncture.
• Looking at things from a singular point of view while interacting with the subject matter experts. You need to look at things from the developer’s view and the user’s view as you interact with the subject matter expert. This helps you get the different perspectives and gain complete knowledge.
• Approaching a subject matter expert without any preparation. Technical writers often fail to respect the paucity of time and other constraints that developers are associated with. It is very difficult for the developers or the design team members to explain in detail every trivial aspect that can otherwise be easily learned through one of the search engines. Hence, technical writers should walk the extra mile and do a little amount of research and preparation even before approaching the developer. Likewise, they should clearly absorb all the information available in the design document to get a hang of the product.
• Not asking enough questions. It is advisable to prepare a list of questions even before approaching the experts. This helps gain clarity about what one wants to gain from the interaction. Some interactions might last only for a few minutes and the writers need to collect the most important information. Hence, it helps having a list of questions. It is also good to send the list of questions prior to the meeting so that the developers are also ready with the answers.

Mistakes with regard to the User

• Having too much information that overwhelms the user or too less information that confuses the user. Writers tend to justify when they are unsure of what information to add and what not to add. Imagine yourself as the user. List the inputs that you want when you try the application for the first time and at later stages. This can help you arrive at the actual volume of information that neither overwhelms the user nor leaves him confused.
• Making assumptions about the audience and going ahead without any clarification. Draw a clear line between observations and assumptions. Inferences can be drawn only if the source of information is authentic. A senior and experienced project manager might give you some authentic information about the probable type of users of a new product. Likewise, an industry report about changing trends can also be a reliable source. More often, you are not sure of the audience. Instead of making assumptions, try to interact with the actual user to get some understanding. While this may be impossible mostly, you can infer about the audience after interacting with the developers and other key people involved in the product design.
• Ignoring the way users tend to use the product. While every writer speaks about getting into the shoes of the users, very few actually do so. It is difficult to look at things from the user’s perspective. This is mostly because of the heterogeneous nature of the users. But, one thing is true for sure. The way the user uses the product is different from the way in which the developer uses it. Hence, do not stick to the developer’s viewpoint.

Mistakes with regard to the writer

• Believing that they know everything about the product by just trying it. Writers also need to know what happens in the background. Some writers believe that it is enough to learn as much as is necessary to convey to the user. But, to convey that information effectively, writers need to know what happens in the background and a lot more about the product before beginning the process of documentation.
• Living under the impression that writing is a fairly simple process. Yes, writing is not as simple as it seems. If a writer has to just construct grammatically correct sentences and deliver them to the user, it would not make any sense. Technical writers need to understand that there is transformation of knowledge about the product and it should be done as a process. Any slight deviation might disrupt the entire flow of knowledge from the writer to the user. It is for this basic reason that some companies designate technical writers as Information developers. They need to develop information that the user can use to carry out his work with the product.
• Ignoring product development meetings. Even though it is not necessary to participate in every meeting where technical elements are discussed, it would be useful to attend meetings such as design meetings, product demos, and presentations that help writers gain a lot of knowledge and save a lot of time.
• Assuming that it is not necessary to know about technology. Writers come in different sizes and shapes. Some writers who hail from a literature background fail to understand the importance of keeping in pace with technology. They find it a sheer waste of time to learn more about technological advances.
• Lacking interest to learn about other product developed within the same company. While it may not be necessary to know about other products that you need not document, it helps a lot to exchange common information whenever necessary. If you are up to date about where the information might be available, it saves the time invested for searching for information.

Ultimately, writers need to realize their role as a part of the entire software development system and that they are not isolated to come up with beautiful sentences and catchy phrases. People have started recognizing the significance of technical writing as a domain the way product design, testing, and development are considered.

Introduction to the Unified Modeling Language

You can construct a house using a load of bricks, nails and other hardware. Yet, to construct a good house, you need to have a planned approach with an estimate and blueprint of how you want your house or building to appear. Architects use blueprints to communicate requirements by expressing your expectations in the form of pictures. These models form the basis upon which the entire house is built. These models also act as a control mechanism to check if you are sticking to plans even mid-way during the process of constructing your house.

Likewise, dishing out lines of code is not just enough to build a software application. Yes, you need to build or construct your application. Initially, you need to come up with models that describe the actions and interactions of the system. You also need to specify the internal functioning of the system so that you can change it as necessary to make it more usable for the end user.

Software professionals borrowed the concept of modeling from the engineering community to enhance the software development process.

One of the definitions of the word 'model' according to Dictionary.com is
“A representation, generally in miniature, to show the construction or appearance of something. “

Models are used to capture and specify the requirements to enhance the ease of understanding for all the parties involved to arrive at an agreement. Engineers construct models of houses and the clients accept or request for changes in the model to avoid problems of failure due to customer dissatisfaction. Architects use models to experiment with possible designs with an aim to innovate while decreasing costs to the optimum. Scientists often use models to master complex systems to clearly explain to everyone and take action on improving the system regardless of the complexity of the system.

Unified Modeling Language

Object Management Group (OMG) is an industry-recognized standardization organization that worked in collaboration with Rational Software Corporation to create the Unified Modeling Language. UML brings together the information systems and technology industry's best engineering practices.

Software blueprints can be written and constructed using Unified Modeling Language. UML is a visual language for modeling and communicating about systems through the use of diagrams and supporting text.

Programmers think and code as soon as the need for the implementation of an idea arises. While writing codes of line is the best way to model, this is not always easily understood by everyone. In object oriented languages, it is difficult for others to understand the classes and their attributes just by looking at the code. Only the developer of the code has an understanding of the classes. UML serves as a common language to aid understanding of the complex classes even to the new members of the team.

UML is a combination of graphical interpretation with well-defined semantics to ensure that different people can interpret the model unambiguously.

UML models can be directly used for construction by connecting to a variety of programming languages. While graphical expression is done using UML, textual expression is done using the various programming languages.

Finally, UML also acts as a source of documenting the various artifacts of the software development process such as - architecture, design, project plans, tests, prototypes, and releases.

Goals of UML

• UML is intended to be used as a general-purpose language for modeling purposes using object oriented techniques.
• It is intended to solve issues related to software development such as large scale, distribution, concurrency, and team development.
• It is aimed to support in the process of software development process by simplifying things while remaining practical.

Simply put, UML is an implementation-independent language to be used regardless of any specific implementation technologies such as Java or .NET.

---

References:

• Learning UML
  By
  Sinan Si Alhir
  Publisher : O'Reilly
• The Unified Modeling Language Reference Model
  By
  James Rumbaugh
  Ivar Jacobson
  Grady Booch
  Publisher: Addison-Wesley
  

Nuances of a User Guide

A User Guide is similar to any other document. Yet, it has its own prominence because it acts as a Bible for the tool, application, or software that we use. The technical writer should hence be very careful while preparing a User Guide. There are numerous resources on the Internet that explain the process of making a User Guide - audience analysis, document planning, implementation, review and delivery. Yet, there are certain nuances of a User Guide that a technical writer should understand and apply effectively.

Why?
This is the first question that appears before executing any task. Some perceived personal benefit has to be there before beginning some task. When the user changes from a very old system to a completely new system, the user guide should begin with specifying a solid reason to upgrade to the new system. Either the new system saves time or money. These are the basic motivators for any reader to go ahead. Yet, there are many other motivators that the technical writer can include in the first few sentences of the introduction to grab the attention of the reader. The user, after perceiving a tangible benefit, will be interested to go ahead and try using the application. The tangibility factor is very significant because users might not actually prefer to use any tool that can make them happy without actually knowing how it brings about satisfaction or happiness. It should either help the user save time, or work efficiently or enhance the quality of work.

What?
Once the user is aware of benefits of using the tool, the education about what the tool actually is begins. If it is a software application, the user should clearly understand the purpose of each function in the software before trying to use the functionality. Likewise, it is obviously important for the user to know the process of the flow of application as a whole. Remember to interconnect the different parts of the tool in this section. The user should be able to relate it to other parts with ease. Users are classified as experts, technicians, specialists, and non-specialists. Since it is the responsibility of the technical writer to cater to all of them, care should be taken to phrase the 'what' part of the user guide to explain it clearly to the intended audience. If the audience includes only experts, the writer is fortunate enough to write this part using the appropriate technical jargon. As the process of finding the exact audience becomes hard, the composition of this part also becomes hard. Hence, the technical writer should avoid any complications and pen down thoughts and experiences in a simple and clear fashion.

How?
Now that you have explained the user what the tool is about, you can go about telling how to use it. There are different style guides available that advocate different ways to do it. Yet, the most popular way remains to break this process into a series of steps so that the user does not get confused while trying the tool. Break down the process into smaller chunks and then you can easily write the process in a series of steps. The technical writer should come up with a good number of topics by getting into the shoes of the user and then write step by step instructions for each topic and its sub-topics. The other important point is that there would always be more than one way to do a particular task. The writer should take adequate care and document all the possible ways so that the user is not confused after treading a new path.

Additional open-ended questions such as who, where, when, and what also provide answers that fill in the required answers for your guide. Ultimately the most important thing that the technical writer has to bear in mind is that the user guide should not display the talent of the writer and the writer’s expertise in playing with words. It should instead be empathetic to the user and clearly answer any questions that might arise in the mind of the user, who actually works with the system.

While the TOC, index, and copyrights page include the essential elements of a user guide, the information should be classified into the following - definition, procedure, and a reference. Structured authoring plays a significant role in determining these elements and it also helps in making the process of information gathering easy.

Talking about Technical Writing

I never imagined technical writing to be interesting until I started my stint as a technical writer. The initial days slipped away easily with enthusiasm and a craving to learn more and master as much as possible. As time flew, I have realized the fact that I have learnt very little and need to learn a lot in this field of technical writing.

Technical Communications is not an emerging field. It has been in vogue ever since the first time a man told another how to write and how to walk. Indeed, our parents are great technical communicators in the sense that they teach us how to eat with a chop stick and how to do so many little things of life. The most interesting thing is that they communicate their message with the fewest possible words. Of course, for a toddler audience the simpler it is, the better it is. Even today, there are many things that we tend to communicate with mere gestures to our friends and relatives.

It is not so easy to establish such a rapport with our audience. I wish all my readers were my best friends and could use all the words I ever wanted to. However, there would be no challenge in such a case. I pine for creative challenges. I admit the fact that technical writing is not a creative job in reality. There are some boundaries and many more limitations. However, I have a penchant for explaining things to others and that makes me stick to product documentation and technical communications.