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.