by Radhika Govindankutty

by Sophia Jose

My first documentation project was on a product based on business intelligence domain. The lessons that I learned from this project are as follows:

1. Creating a template: Think of all the styles that would be needed in the document. Write down the styles and see that they are created if not already present. Use the pre-built style names for headings (Heading 1, Heading 2...). In MS Word, this is advisable so that cross-references can be created directly and not through bookmarks.

2.  Interacting with the Subject Matter Experts (SME):   It is very important to gather information from the SMEs to prepare documents. SMEs are usually very busy people hence they might not be able to give enough time to gather all the information. So, within the short span of time allocated, collect as much information as possible.  This is possible by preparing a list of requirements needed from the SMEs before the meeting. Even when you don't get the information you want, be patient and polite to the SMEs.

3.  Writing project emails: Never use informal greetings like “Hi there” to address any one in a formal email. It is always best to opt for the more conventional "Hello". Email content should be concise and error-free. It is good to use the same e-mail thread and subject for the same topic.  Send gentle reminder emails to the SMEs when they do not reply to the queries.

4.  Writing procedures: A good procedure is accurate, brief, and should communicate what readers need to know. To write a procedure for a product, it should be tested. All procedures should start with a lead sentence. One step is used to indicate one action.  Always write actions in the order in which they happen.

5. Graphics: Always check that the type of graphic captured is what the client wants—for example, gif, jpg, png. Place all graphics in a separate directory under the document directory.

6.  Copying text from one template to another: When working in MS Word, copy the text from one document into a notepad file and then paste it in the new template. This will help to remove all the styles that belong to the old template.

7.  Check the document thoroughly before sending it for reviews and final submission: Have a checklist of items that need to be done before the document is sent out.  For example, the name of the file must adhere to file naming conventions, there should be captions for all tables and graphics, always update the TOC and index just before the document is finalized. 

by Aparna Mogra 

Technical communication is the process of conveying information through writing, speech, and other media to a specific audience. A technical communicator has the responsibility to step into the shoes of the user who needs to read the documentation and work with the software in the course of their daily work or for specific reasons.

In my short stint as a technical communicator, I have realized that understanding the software being documented is one of the most important aspects of my work. In many cases, a technical communicator would know more about the software than the developers themselves, bugs included. As a technical communicator, one must never assume anything. It is always better to ask questions than to make mistakes based on wrong assumptions. More often than not, the work of a technical communicator requires working with the software while it is still in the final development stages. It is at this time that a technical communicator ends up testing the software.

Something I noticed in my own work as a technical communicator was that software created for in-house employees is customized for their requirements. This means that unless you understand the entire business process, it is difficult to understand the software. This definitely requires help from subject matter experts without which a technical communicator cannot use the software efficiently.

Creating technical documentation for a software application requires a great deal of testing. None of the features can be left out and there may be cases where improvements can be made to certain features. As technical communicators, we need to think like an ordinary user and ask ourselves whether we can use the software application without the help of a user’s manual. If it can be done, then the software has served its purpose–to make work easier for those who use it. On the other hand, if you have to break your head trying to figure out what a button does or what a check box implies, then the software needs a bit of tweaking. 

Software that is set for release to the public is designed in such a way that any user with a basic understanding of application usage is able to work with it. Such applications have features that are self-explanatory and in most cases, users do not have to refer a user’s manual.

In a poorly designed application, the data entry flow may be difficult to understand. There are many instances where the standard business process is easy enough to understand, but implementing the same in the software is an arduous or near impossible task. In large systems there may be quite a few modules that are rarely used by the intended users, and hence bugs are not discovered until later, when the documentation specialists get their hands on it. More often than not, developers do not take into account the software’s usability by a general user. To get a near-perfect document, the technical communicator must be able to fully utilize all the features of the software. 

References:www.wikepedia.com

by Sreelatha Menon

An in-house practice session for Agile Training was conducted by Write Concept on Saturday, 5th June, 2010.

The workshop aimed at giving us an overview of Agile methodology so that by the end of the session all of us have a basic understanding of the same. The day-long session was highly interactive and focused on the popular Agile methodology - Scrum. The instructor (Vasanth) used slides, videos, exercises, and handouts to provide us with a working knowledge of Scrum.

Scrum was a totally new concept for all of us. We learned about the benefits of Scrum over the traditional waterfall model. Scrum is more beneficial as it is more realistic and emphasizes on building working software that people can get their hands on quickly, versus spending a lot of time writing specifications up front. This is because Agile development focuses on cross-functional teams empowered to make decisions and rapid iteration, with continuous customer input along the way.

Product or application development in Scrum structures development in cycles of work called Sprints (2-4 weeks). These are time-bound and are never extended. At the beginning of each Sprint, items are selected from a prioritized list called Product Backlog. The team commits to complete the items by the end of the Sprint. Every day the progress is reviewed and at the end of the Sprint, a working product that is integrated, fully tested and potentially shippable is available.

In Scrum there are 3 roles - the Product Owner, Team and the ScrumMaster. The Product Owner is responsible for maximizing return on investment by identifying product features, translating these into a prioritized list, and continually re-prioritizing and refining the list. The Team builds the product that the Product Owner indicates and is a team of seven plus or minus two people. For a software product, the Team might include people with skills in analysis, development, testing, interface design, database design, architecture, documentation and so on. Scrum Teams work best if all members are 100% dedicated to the work for one product during the Sprint and avoid multitasking across multiple products or projects. The ScrumMaster helps the product group learn and apply Scrum. He or she serves the Team, protects them from external problems, and educates the Team in the skillful use of Scrum. A ScrumMaster is a dedicated member of the team and can come from any background or discipline. The ScrumMaster and the Product Owner cannot be the same individual.

The first step in Scrum is for the Product Owner to articulate the product vision and make a list of features called the Product Backlog. At the beginning of each Sprint, the Sprint Planning Meeting takes place. It is divided into two distinct parts. In Part One, the Product Owner and Team review the high-priority items in the Product Backlog that the Product Owner wants to implement in the Sprint. In the second part, the Team focuses on detailed task planning for how to implement the items that the Team decides to take on. This meeting will often last a number of hours, but no more than 8 hours. Each member decides how much time can be spent on Sprint-related work and how many Product Backlog items they can complete in that time. The Product Backlog items are broken into individual tasks and recorded in a document called the Sprint Backlog. Scrum encourages multi-skilled workers who have the capability of doing many tasks and can help out whenever possible. Teams use a visual task-tracking tool to check the progress of 'Not Yet Started', 'In Progress' and 'Completed' tasks.

Once the Sprint has started, the Team has a Daily Scrum meeting that happens every workday at an appointed time.  Only three things are reported in this meeting by each member to the other Team members:

1) What they were able to get done since the last meeting.
2) What they are planning to finish by the next meeting.
3) Any blocks or impediments in their way.

If there are any blocks, the ScrumMaster helps the Team members resolve them.

Every day, the Team members update their estimate of the amount of time remaining to complete their current task in the Sprint Backlog. Following this, someone adds up the hours remaining for the Team as a whole, and plots it on the Sprint Burndown Chart. The Product Backlog may also require refining--done by scheduling a focused workshop near the end of the Sprint, so that the Team and Product Owner can do this work without interruption.

The duration of the Sprint is never extended--it ends on the assigned date regardless of whether the Team has completed the work it committed to or not. After the Sprint ends, there is a Sprint Review, where the Team and the Product Owner review the Sprint. The Sprint Review involves "inspect and adapt" of the product. The Sprint Retrospective, which follows the Sprint Review, involves "inspect and adapt" of the process.

At this point, some items have been finished, some added, and some dropped. The Product Owner has to ensure that these changes are reflected in the Release Backlog. In addition, Scrum includes a Release Burndown chart that shows progress towards the release date.

Following the Sprint Review, the Team is now ready to start another Sprint cycle. Scrum is therefore a set of practices and also a framework that provides transparency and a mechanism that allows for change through inspect and adapt. Implementing Scrum is not easy but the benefits are visible and worth the effort.

Some links to better understand Scrum are given below:

http://www.goodagile.com/scrumprimer/scrumprimer.pdf
http://justwriteclick.com/2007/07/02/writing-end-user-documentation-in-an-agile-development-environment/

'Succeeding with Agile' by Mike Cohn is a useful reference book for those interested in knowing more about Agile.

At the end of the workshop, we definitely had a lot of questions but also knew quite a bit about Agile and Scrum!