Monday, September 22, 2014

Information Architecture at Cisco - demistifyed

The STC learning session held at Cisco on 20th September, can probably be summed up with the following quote

“Without understanding how people use your products and information, you are more likely to develop information that meets the needs of your authors or your subject matter experts rather than those who need to use your products and services to meet their goals and get their jobs done”

- JoAnn Hackos (in her book Information Development - Managing your Projects, Portfolio and People).

I've not comes across another statement that gets this close to home.

Here are a few notes I took down and hope you find useful.

  • Before Sandhya and team started the presentation, they asked the audience what their expectations were. The expectations ranged from understanding the new methodology, tools used, how this method impacted UI and Non UI products, how quality goals were measured, etc.
  • The session started with a video recording from Denise Asplund, the Global Head for tech com at Cisco. She welcomed the audience and gave a short introduction to the topic.
  • So it all started with the problems that the team were trying to solve. Some of the problems with tech comm at Cisco included a lot of content (unwieldy and huge), content difficult to find, finding relevant content, content that included marketing language, content that made the product appear more complex than it actually was
  • The first step at solving this problem was to find out where tech pubs was actually needed in the product lifecycle. They found that they were needed only in the pre-implementation, implementation and maintenance phases of their lifecycle.
  • Top down approach used to buy in stakeholders. Don't even try the bottom up approach. You might end up like that... bottom up.
  • Tech pubs gets involved in the process only after a customer is on board. Thus there was no need to sell the product to existing customers. That task is left to marketing/sales. All such content was removed. The team refused to include marketing content. Lucky team!
  • Customers who were used to seeing marketing information (about features, etc) were pointed to marketing information (managed by other teams)
  • Different types of users, their skills, and experience levels were analyzed and personas created.
  • An exercise to identify key workflows was then made and the workflows were mapped to the personas.
  • It was only after the above steps were completed that the documentation set was finalized.
  • Content strategy and content delivery models developed. (Who to write to, what to write, what not to write, defect workflow, etc)
  • Use web analytics whenever available to understand content/product usage. Talk to marketing/sales when the product is new. Use use cases.
  • Two important questions to keep in mind when creating content – Who is the product aimed at? Why would someone use this product
  • Some of the questions to ask to arrive at conceptual content – What is this feature about, why is it required? What problem does it solve? Who will benefit and at what stage (of the lifecycle) will they use the feature? What problems can arise (troubleshooting)
  • The first step at this change is to commit to this sort of information architecture. It requires a mindset change and can only succeed if driven from the top. This method needs to align with the development methodology used (agile/waterfall)
  • When trying to influence stakeholders, include reasoning for the change
We at GT Nexus, also use a workflow based documentation approach. Of course our domain (supply chain) is much more complex, with users interacting with each other using our product and processes. What we did was to chart out the big picture as a workflow. When would each kind of user perform a certain task. How does that task impact other stakeholders in the process? Users not only get to see the big picture, but can also figure out where they come in. 
I wish we could show you some of the documentation as examples. But then, we'd probably have to kill you ;)

What could have been better.
  • Most of us had to wait outside the gate for nearly an hour. Cisco has an 'escort' rule in place, where visitors need to be escorted by employees at all times. (I was thanking my stars that the rest rooms didn’t need access cards! You know... or we'd need escorts to go as well.) Reception didn’t seem to be aware that an event was happening. Neither did they know whom to call and inform. The event was supposed to start at 10, but even after half an hour, we were at the gates trying to 'negotiate'. We were let in only after 10.30 am. The phone number given on the confirmation email was not being answered. Not a very pleasant experience to start with.
  • Both the font size and colors used in the presentation made it very difficult to view/read the text. I've noticed this at other sessions too. Perhaps STC should have a say in this, publish certain guidelines and maybe review the presentation once before it is D-day. Please.
  • Disappointing to see the poor attendance at such events. Even from Cisco. From what Sumathy says, she hardly sees any attendance from writers in events held in other companies. That’s probably why someone had the idea of working on the mountain instead of Mohammed. Perhaps it time to go back to Mohammed. 
  • Registration shouldn't be free. Charge a nominal amount which gets reimbursed at the venue/refunded back to the account. Those who don't turn up... well they just treated those who attendees to some snacks : )
The icing on the cake. 

Some time back, I had written an elaborate procedure on TWIN on how to file one's income tax returns online. (I'm sorry to say this, but the TWIN site is currently just a shadow of what it once was. Search doesn't work. We can't create new content. Lots of spam comments. Articles are missing and there's a general apathy that gets under your skin. I could have have linked the article here, but can't find it). The article was titled 'Fire Your Accountant' and had a step by step procedure on how to look up your form 16, identify and use the required information to complete and submit the IT return. Believe me, it's much easier to file returns now. But the procedure documented the process when it was not so simple.  That's putting it mildly.
So coming back to the subject, I was pleasantly surprised when one of the writers who attended the workshop came to me and said he was able to file his returns by just referring the page I created. Mighty pleased. 
We have come back full circle to the quote we started with. Now that's RTFM for you!

Sunday, September 21, 2014

Madcap - Sanity in the Maddening world of Documentation

The Webinar started (a few minutes late – waiting for late comers:) with the presenter – Michael Hamilton introducing himself. Mike is the VP – Product Management for Madcap. He has a degree in Physics and was initially working in the Nuclear Power Industry before a transition to documentation. He gave us a quick summary of his work as a Product manager for RoboHelp before starting off with MadCap. He has over 10 years experience in documentation. He co-authored the training curriculum for RoboHelp in 1996. I've got to add that Mike went great lengths to make this session easy to comprehend and really informative.

What or Who is Madcap?
In two words – it is a complete documentation solution. (Did I say two words? Sorry – scope creep!) Madcap focuses 100% on content authoring and documentation. This company has the expertise (10 – 25 yrs) of several industry experts who were earlier working with RoboHelp, eHelp, etc. Its products have become very popular in the documentation industry because of the ease of use, innovativeness, versatility, scalability and comparatively low price. A few feathers in the (Mad)cap:
  • Was the number 3 authoring tool in just 9 months after release
  • Profitable since the first month of shipping Madcap Flare
  • Selected as a showcase application by Microsoft for Visual Studio 2005 and XPS
More about Madcap
  • Formed in 2005 - some of Madcap customers worldwide include - Yahoo, Google, GE, 3M, Oracle, Motorola, HP, Nike, Xerox, etc.
  • Does not have the word help in any of its names as they believe that help is only a part of what the software can create.
  • Bulk of business is from knowledge base or general publishing – manuals, procedures, policies, etc
  • It is built on the differentiation model and has 3 value propositions:
    • Quality – Not sold as enterprise software, but as regular shrink wrapped solution. Unlike enterprise software, they cannot release update patches - therefore has to be checked thoroughly before release
    • Low Cost – Flare costs 900$ per user. Madcap also have a competitor pricing model - if you have a competitor product, you get a 400$ discount!
    • Scalability – You can start with just a single copy and can thereon add capabilities according to your publishing needs. You can pick and choose what components you want to use! Server products, usage tracking, translation, etc are some of the modules offered. You can do all this by yourself on their Web site where all the pricing options are available – no hidden costs, no marketing gimmicks!
Madcap Solutions - Holistic approach to documentation
The software offered can be categorized under these topics:
  • Authoring
    • Madcap Flare– Flagship product - Advanced full authoring editor used for both online and print publishing.
    • Blaze – Same functionalities as Flare but can only be used only for print publishing. Priced cheaper than flare.
    • X-edit – Limited function - template based authoring tool. This can be used when extensive authoring is not necessary and content only needs to be populated in different templates. Users cannot change styles – thus a very controlled authoring tool.
    • X-edit (Review) – Sensibly, a free utility. As the name indicates – used by reviewers. Has limited functionality – reviewers can leave comments. The tool includes style sheets, etc to render content exactly as is viewed in Flare. Brilliant!
    Note: If you have Madcap Flare, you do not need any of the other authoring/publishing tools from Madcap.
  • Multimedia
    • Mimic – Similar (better!;) to Captivate – used to create moving pictures with sound - simulations and tutorials. Supports single sourcing of multimedia.
    • Capture – used only to capture images. The difference with other multimedia software is that when an image is captured, it is saved as a master image without any reduction in resolution or detail. This ‘master’ image can then be used as a single source to create different output files (profiles) based on size, pixel, dpi, type, modifications, etc. You will never have to capture the same screen again!
    • Echo – used only to capture sound. This is available separately because some customers wanted a stand alone audio capture tool that could publish audio to complement text.
    Note: Madcap Mimic performs both Capture and Echo functions.
  • Advanced Support (server products)
    • Analyzer – Inside the firewall – can scan and analyze all content. Reports generated include:
      • Tech Reports on broken links, missing images other technical issues.
      • Efficiency reports – e.g. there are 15 styles sheets that are not being used.
      • Linguistic reports - Very helpful in localization as it can find similar phrases thus reducing translation costs. Analyzer flags such phrases and recommends a standard phrase. E.g. Phrases like ‘From the File menu, click Save’ and ‘Click Save from the File menu’ will usually mean paying twice for two different versions of the same instruction – if not for the analyzer.
    • Feedback – Outside the firewall – customer facing. Reports on search terms used, tracking usage in a given time frame – what pages are read -how often, etc. Web 2.0 capability that allows users to comment on published documents in real time.
    • Team Server – Enterprise CMS solution that is scheduled to release this year. Automate and manage your content across the enterprise with this part of the solution.
  • Localization
    • Since Madcap files are standard XML files, it is easy to use with translation systems like Across, Dejavu, etc
    • Lingo – translation tool - recognizes all the files that require translation - Table of contents, glossary, etc. Lingo builds a master list of all such files that must be localized.
All the components above can integrate tightly to work together to give you a solution for almost any kind of documentation need.

Madcap Software - High Level Concepts
  • Single Sourcing
    • Single sourcing explained with an example. This solution involves creating content once and using it many times. A Master Source Files is created that can deliver variations as output - based on the need.
    • Advantages of single sourcing explained – Do not need to update all documents every time a change is required, only the source (master) file needs to be updated
    • Single sourcing process – Build Master Files > Add conditional Tags > Define Publishing Tags > Generate Output
  • Topic Based Authoring
    • Topic based authoring vis-à-vis linear authoring and the challenges faced.
    • Topic is defined as a discrete unit of content about a specific subject, identifiable purpose [b]that can stand by itself[/b].
    • Each topic is like a building block that can be reused to build different documents.
Flare Workflow

Step 1– Import existing content. Capability to import from Word, FrameMaker, HTML or XML files, Robohelp, Help Projects. DITA is currently in BETA.
Step 2 – Built in flare editor used to edit or create additional content
Step 3 – Publishes to various outputs – HTML Help, DotNetHelp, Web Help, Word, PDF, Adobe FrameMaker, Microsoft DOCX, Microsoft XPS, XHTML Book. Exporting to DITA is also in BETA.
Madcap Flare is the only tool in the industry that can export content back into FrameMaker.
Flare Demo
  • Trial version of Flare can be downloaded from
  • First time users can make use of the getting started section – especially the video tutorials
  • The same help is also available on the Madcap Web site - eliminating the need to download a trial copy just to view help
  • For users of RoboHelp - The tutorials leverages existing knowledge of the tool (RoboHelp) and compares how the same tasks are performed on Flare
  • There is a section in the video tutorials that explains single sourcing on Flare, how to use style sheets mediums, variables, conditional markers, etc.
  • Mike’s Demonstration went on to show how to import content from different sources, the navigation pane and the WYSIWYG editor
  • The navigation pane makes topic based authoring very easy
  • The visual block bar allows authors to view the structure (graphical view) of XML outside the content area – helpful for authors who would like to build expertise in XML
  • The Visual block bar allows elements to be moved around with no effect on the formatting. Handles manipulation of lists extremely well
  • Tables was next. Flare uses style sheets that make formatting a huge number of tables – a breeze
  • Integration of multimedia tools was explained by handling images and making changes on the master image using Mimic
  • Sending content for review, Using the X-edit tool to commenting or add annotations was also shown
A few questions that were asked during the Q&A session:
  • Would I be able to integrate my online help files into visual studio? Yes – depending on publishing format
  • Is there a migration path? Yes
  • Price is high for emerging economies – are you considering hosted services? Lingo – translation tool is currently available on a subscription model.
  • Is it possible to find and replace tags? (Mike seemed to be waiting for this question) Short answer – You Bet! Mike demonstrated this later in the webinar.
  • Can 2 or more people work on the same project at the same time? YUP! 2-3 writers can use common network drive. 5 or more authors need some sort of source control mechanism like CVS.
  • A question on publishing to XHTML – was answered with a demo
  • Can you use feedback from non mad cap products? Not currently
  • If we have integrated web help with the application by calling the map ids, can the same implementation hold good to call the web help generated by MadCap Flare? Yes – and Mike happily showed us how it could be done.
  • How do you apply a conditional tag? Mike showed us how it is done and shared a best practice in the process.
  • Can you explain how to add a header or footer to print output? He did!
  • Does Madcap Flare have version control? No
  • How does it manage images? Does it support meta tagging of images? No
More questions? Send them to
A suggestion on future webinars - Everybody could benefit if the questions asked during the Q & A session are shared with all the attendees.

Day 2 at the 14th STC India Conference

The first session I attended on day 2 was about Videos as a genre in Technical Communication. This paper was presented by Nabaneeta Sarkar and Faraaz Mohiuddin.
  • Started with some statistics about how many words can be conveyed in a minute of video.
  • Videos capture attention and create curiosity
  • Result in faster transfer of skills
  • Videos are more involving to the user when compared to plain text
  • Videos make it easier to understand concepts and there is a higher receptivity to learning
  • Better retention and recall of information. Users can retain 50 percent of what they watch but just 10 percent of what they read
  • Lower data storage costs, availability of higher bandwidth, portable devices, tools for recording and editing, greater access all contribute to why there is an explosion of videos on the internet
  • As much as 60 hours of video are created on the internet every minute
  • Cisco predicts that video will account for as much as 62 percent of total internet traffic
  • Intel predicts that the future could see as many as 500 billion hours of video
  • Examples of how videos are already being used successfully in technical communication - Telstra, Adobe TV and Citrix TV
  • Video trends include a lot of how to videos, reduction in tech support calls, product reviews, social bookmarking, tagging and sharing
  • Text is dead, videos are more conversational
  • Videos are not required everywhere
  • Text still rules when it comes to legal documents. While news analysis is saved for text, knee jerking breaking news is best shown as videos
  • Some best practices include creating playlists and progressive playlists, applying gamification concepts, creating video table of contents and 'let me try' videos where the user controls the pace of the video.
  • Challenges include addressing broad audiences, the possibility of sub standard content damaging your brand, demanding audiences
  • To create good videos, in addition to writing skills, one needs to be good at design and production, writing for a universal audience, information architecture, building viewer experience and content curation.
Percy's Lets get the Technical back in Technical Writing presentation was probably one of the more 'hard hitting', closer-to-home kind of presentations that a lot of people seemed curious about. The presentation hardly had any text and consisted entirely of well selected, apt images. Do look at the presentation when it's posted, especially the 'ice breaker'.
  • He talked about how users are becoming more demanding
  • And about how Technical writing is evolving
  • It's important to immerse yourself in Technology and not just scratch the surface.
  • If that means clicking the Submit button, do it! (If a bomb is going to go off, assume it's going to go off in a certain neighboring country ;)
  • Important to see the big picture and find the connections between everything you do
  • Explain like you are explaining something to a 3 year old
  • Don't be lazy!
  • Benefits of getting technical include increased ROI, added value, reduced dependency on SME, increased credibility and of course, better career prospects!
  • Getting more technical also increases your engagement with work.
For the second time, he talked about his 'forgettable' Twin days. The last time, when he presented a topic in Bangalore, he said that he was a big time flamer on Twin. Now that probably explains why he seemed to be heckled by one of his possible 'victims' during Q and A. But I must say, he handled it extremely well.
Bindhu and Bhavana presented Alfresco, an open source enterprise content management tool
  • They started by describing what a CMS is and why an organization would use a CMS.
  • Reasons to use a CMS include improved operational efficiency, collaboration and security
  • Reasons that hold back users from using a CMS are cost, training and complexity
  • Alfresco can be installed on any platform that supports Java std edition
  • It's easy to download, install and deploy and the UI is very user friendly
  • Described various offerings for various needs. Only the community version is free.
  • Described workflow, how it can be integrated with Google Docs and how it allows users to edit the markup language
The Social Documentation presentation was about user generated content and how cumulative knowledge of users, fills information gaps.
  • Social Documentation offers real time solutions to user queries
  • Uses social networking sites, wikis blogs forums
  • Leads to increased interaction and collaboration
  • Content is user centric as it is created and owned by users
  • Discussed new roles like community manager and content curator who were required in this kind of documentation
  • Complements end user documentation
  • Challenges of social documentation include maintaining accuracy of content, formatting, avoiding repetition, implementing standardization and consistency and archiving
  • Use social media to get closer to users
  • Social documentation involves less writing but more curating
Anima Palshikar started the Competitive Analysis presentation by taking a pulse of the audience expectation.
  • Competitive analysis is a decision making method that allows us to understand similarities and differences between available options
  • Helps understand the market and competition
  • Identify strengths and weaknesses and identify scope for improvement
  • She explained why technical writers are most suited to write competitive analysis
  • The approach to writing a competitive analysis is to believe that your product is the best.
  • It's important to identify the audience and choose your competitor. Also identify your strengths and competitor's weakness
  • Now your user's psychology and identify your pitch line
  • Study all available literature, collateral and be familiar with the user interface
  • Some of the points to compare are features, value for money, user experience
  • Competitive analysis must be interesting and useful to the reader
  • It must be backed by appropriate resources
  • Improve the reader's knowledge regarding the product and motivate them to ask more than the competition
  • Penetrate your customer's thought process and motivate them to ask more questions than the competition
  • Highlight what users are enjoying and present weakness (if you must) of the product in a convincing manner
  • Address cost problems as part of the Gap analysis.
  • Analyze the most compelling features, requirements and scope
  • Case studies with visuals are a must have for competitive analysis
  • Other must haves include business criticality of the product, market trends, brief insight into what the competitor is offering
  • A good eye for detail, an analytical mind-frame, an understanding of customer perceptions and psychology and the right attitude are part of what it takes to be good at competitive analysis
  • You don't win every deal. An important thumb rule is that you should be careful that none of all this work should ever make you lose an existing deal. Double whammy!
  • Concluded the presentation with some of the places where competitive analysis is used. These include sales and marketing, branding and advertising, newsletters, core development and documentation.
Engaging with your users was a presentation from Fredrick Menezes. Fredrick usually organizes quiz competitions at STC each year, but for whatever reason, there was no competition this time.
  • Started with why it is important to engage with product/documentation users
  • Users can be found internally (pre-sales, consulting services, technical support) or externally (user conferences, promotional events, product beta events, social networks, feedback links)
  • User surveys can be used to engage with users. These can be deployed on mailing lists, social networks or internal groups
  • Ensure that the questions are specific to a product.
  • Multiple choice question along with space for comments, works best
  • Promise an incentive to participate (Fredrick mentioned that incentives made a big difference in the response rate. However, he didn't have data to show what is the difference in the response because of the incentive. The other observation he agreed to was that some of the responses may not be genuine and may have been submitted only because of the incentive)
  • Another way to engage is to request for a presentation slot during product Beta events.
  • Seek out specific participants for a one-on-one conversation
  • Don't be defensive about documentation errors or product flaws. Learn to listen!
  • Once you have a foot in the doorway, explore further engagement opportunities
  • Use delegate kits to deploy surveys during user conferences. Offer an incentive for returned forms
  • Request a presentation slot only if the topic you have is reasonably interesting to a majority of participants
  • Negative feedback and challenges are important. Collect reactions.
  • Seek out presenters who could reference documentation when applicable
  • Request for a stall or table space in user conferences
  • Special meetings can be used to discuss customer engagements with account managers
  • Gather background information about customers and industry before these meetings. Go prepared with an agenda. Prep your teams
  • Once the survey results are in, analyze your responses and prepare reports
  • Use the inputs to formulate going forward strategies
  • Let users know what actions have been taken to address concerns
  • Get new initiatives validated by users
Melanie's presentation on Editing for Non-native Speakers was brilliant. She talked about her experiences working with Chinese writers. She is an American editor with over 30 years of work experience. The last time I heard about the Chinese was from Sunita Agarwal in her presentation about how Tibco was getting the documentation done out of China. But Melanie brought us better news.
  • She delighted the crowd with her opening statement which went something like this. "It's unfortunate, but you know how jobs are moving to China because Chinese developers are turning out to be better than their Indian counterparts? Well, we DON'T have to worry about the same issue when it comes to technical writing"! to which the crowd responded with thunderous applause.
  • Her presentation was punctuated with hilarious pictures of signs that were translated literally into English. I'm sure you've seen them in forwarded emails. If you have not, make it a point to check her presentation when STC India makes it available.
  • One of the reasons why it's a challenge to edit non native (read Chinese) work is because of poor translation
  • Machine translated documents are particularly bad
  • She touched upon how the Chinese learn English as a subject. Though they study English for 10 years, many of them can only read and write English but can rarely speak the language.
  • How the one child policy has spoiled rotten the Chinese kids
  • The problem probably starts with the teachers who can't communicate in English
  • Then most of their text books are Chinese authored and fraught with errors
  • The primary text books are in UK English, about 25 years old
  • High School and University are in US English as perceived by Chinese authors
  • Most students learn English through memorization
  • Mexicans also learn English in the same manner
  • Students read classic literature; learn big words that they don't know the meanings for, nor can they pronounce
  • Chinese students think that English is spoken like how it is in classic literature. Who art thou? Where goes't thou? Why doeth though sayeth that Arunachal Pradesh is part of thy territories? When you talk about English to the Chinese, it's books like Pride and Prejudice that come to their mind. That's how they think English is used.
  • The fact that there are hardly any copyright laws is also a challenge
  • We then looked at the Chinese language and how the role it played when it comes to English
  • Chinese is a rather vague language but can be descriptive. Uses obtuse forms of expression that does not work in technical communication
  • The Chinese language uses guidelines (suggestions), never instructions. So imagine describing a procedure!
  • It has over 40,000 ideograms or characters. (Aren't you glad your kids aren't studying Chinese)
  • Most people can understand 3000 to 5000 characters. The government considers all those you at least 2000 characters as literate
  • You need to know at least 3000 characters to read a Chinese newspaper
  • Melanie herself knows about 800 odd Chinese characters after nearly 8 years living in China
  • Writing Chinese characters is an art (calligraphy)
  • Students also learn Pin Yin, a Romanized form of writing Chinese
  • Homework usually involves copying something from a textbook
  • Essays express opinion. Writers are not encouraged in critical thinking
  • The key objective is to do well in an examination no matter what it takes (I see some similarities with Indians!)
  • Other than providing suggestions instead of instructions, the other challenge is that the Chinese use a lot of metaphors that don't mean much when translated to foreign languages.
  • Translators don't know how to translate infrequently used characters used in highly technical documents
  • The style of communication is to present EVERYTHING that one knows about a subject and then allow readers to draw their own conclusions
  • Common issues includes lack of organization, redundant information, need to know information is missing and 'who cares' information is more!
  • Long sentences in the passive voice with obscured meaning
  • Editors need to explain the edits to the author/translator and help increase their understanding
  • Really helps if the editor can speak the other language
  • Pay attention to the intent of the document so that it meets the needs of the intended audience
  • Delightful examples of signs that were translated literally into English.
  • Most importantly, be respectful and make the writer/translator understand that you are trying to make everyone look good
The final session I attended was on Adaptive Content. This was presented by Amulya Suraj
  • Adaptive content ensures that the content renders well irrespective of what device you use to view it.
  • This is becoming more important given the shift in how the world is accessing the internet and how content is being consumed.
  • Adaptive content is structured in a hierarchical manner to use format free XML. It uses filters and layers so that the output can be viewed in multiple channels
Yeah, I know. You are tired too at this point :)

Inspiration at the 14th STC India Conference (Day 1)

What better way to start this post, but with a good news and bad news scenario? The good news was that this time, STC was back in Bangalore, closer home, after a gap of over 3 years. I’ve been attending these conferences regularly since 2008, when it was held in Pune. So there was no need to worry about which new language I had to learn. The crowd in Bangalore wasn't as big as it was in 2009. Over the course of these two days, I went about furiously filling the 20 page notepad with as much information as I could.
And the bad news?
My handwriting hasn't improved since the last conference. See - Delayed Notes. It seems to have become so bad that I'm considering engaging a linguist to identify what language it is!
Day one started with what we can call an STC record for the shortest welcome note! Thanks to this, we were actually ahead of schedule for most of the day.
Sairaj Vaithilingam, Asst Vice President and Global Head of Cognizant Interactive, was the chief guest and spoke about how he’s moved up since starting his career as a Technical Writer. He spoke about how 3 things.
  • Who are we? (Dang!)
  • Change (Not the kind that jingles)
  • Innovation (He confessed that this had to be part of any presentation)
He asked the audience why technical writing existed in India. Was it because it made sense to co-locate documentation with development, or was it because technical writing is a core business function? Currently, it is the former. What did he think tech writers needed to be considered the best?
  • Strong fundamentals in technical writing concepts
  • Ability to constantly add business value
  • Consultative capability that include domain, business and product knowledge
And to be the best, every technical writer should aim at being in the top 3 percent of an organization.
How could technical communicators get there? By innovating. He cited the example of the Tata Nano. The engineers had to build the car after considering the cost of every screw. If it took 2 screws to fasten something, engineers had to think how the same task could be done using just one screw (or get screwed!). The same logic can be extended to technical writing to improve productivity, quality and presentation.
Parth Mukherjee, was not just another keynote speaker from Adobe. His presentation was both informative and delightful. It was studded with statistics and wit. If there was any marketing done, it was done very tastefully.
  • He started with 3 ways to look at the future; as a writer, reader and marketer.
  • He talked about three implications that consisted of an expanding world where people migrated to different parts of the world and 3% of the population, being born in different place from where their parents were.
  • Everyone has an ROI (unless they were a liability in the first place!)
  • We will work in groups. He talked about an interesting experiment by Penguin where 1500 writers and editors worked together to write a collaborative blog. See Million Penguins
  • See Coke’s vision of using content in Coke 2020
  • Attention spans are reducing. Keeping users engaged is becoming more difficult
  • The impact of how hand held devices are penetrating the market and the importance of adaptive content
  • Provide context and user sensitive content
  • Multimedia will replace text. He cited an interesting example of a video that talked about increasing reading speed!
  • Use global English, keep it concise and be consistent with terminology
  • I loved the way he came back full circle at the end by urging the audience to view things as a writer, reader and marketer.
Everyone has their favorite list of speakers. Some have favorite topics and still others have favorite organizations when it comes to selecting a paper. But what do you do when you can’t decide which session to attend because all of them promise value. You’ll have to pull out your hair when they are scheduled to present at the same time … in different rooms! That's why choice isn't always good! When you delve on it, you realize that you should actually be paying only 30 percent of the conference fees ;) I wish I could be at 3 places at the same time! Anyway, I chose to demystify myself on search. Here are some notes I jotted down.
  • Improving search involves optimizing your website for keywords, tags, introductory text, the home page, links and content structure
  • Search optimization efforts can be monitored using checklists and analytics
  • Topic hierarchy should follow a pyramid structure. This reduces the chances of duplication
  • Users must be able to get to any topic within 3 clicks
  • The pyramid structure has the home page at the top of the structure, followed by overviews and finally the tasks, concepts and reference topics
  • Any effort to improve search improves usability while maintaining content structure
  • It’s important for you to adapt to your user’s preferences, search terms and keywords than to teach them to learn to use what you are using
  • Discussed barriers to indexing.
  • Identify keywords users use and work them into your content
  • Establish the relative importance of each page. How far a page is from the home page determines its relative importance
  • Back links and breadcrumbs have proved to be invaluable in search. Well linked topics appear higher in the search results.
  • Do not use jargon, irrelevant keywords. Do not create a long list of keywords. The recommendation was 1 or 2 keywords per 500 word page.
  • Search engines focus more on text within special tags. This includes page titles, topic titles (H2 and H3) and Introductory text. Ensure that these are accurate, contain search terms and are descriptive enough
  • Search engines only understand text. So it’s imperative that media content is translated to text for it to be picked up by Google’s (or other search engine) spidermen!
  • Tags to be used depends on the markup being used.
  • Using the Alt and Desc tags not only ensures accessibility of your content to the differently abled, but also improves search
  • Statistics show that the introductory text is more important than the title. While 30 percent of users decide to go to a page by looking at the title, 45 percent do so by looking at the introductory text that is populated along with the title on the search result page
  • The first 25 to 30 words determine if a user is going to click the link or not. Make it count!
  • Work your keywords into these 25 to 30 words.
  • Home page could contain links to often done tasks, getting started links for new users, high level topics, tutorials, scenarios that familiarize users to your product. Could also contain links to troubleshooting topics
  • Group links into logical units. Do not cram links into a page
  • Important to link related topics. Link concepts to tasks and references.
  • Create mini table of contents instead of long TOC
  • A sitemap makes it easier to rank relative importance of pages
  • A page must contain 300-500 words. Studies show that such pages are found higher up in the 'pecking order’.
  • Ensure that there are no broken links, content is easy to navigate, non text matter contains descriptive text and no duplicates
  • Search analytics should give you search terms and phrases used by visitors, topics browsed, topics that cannot be found by the search engine
  • Submit help system URL to search engines
  • Use search engine webmaster reports to improve searchability
  • Net Insight was one of the analytic providers mentioned
  • To the question, how soon can I start to see results, the answer was that after submitting content it would take 3 to 4 days. However, you’d want to wait for at least 2 weeks before you check for results.
  • Meta tags are no longer relevant and are ignored by search engines.
The highlight of the conference, to me, was the opportunity to meet Pranav Lal, a visually impaired freelancer (can’t call him a writer, he dabbles in so many things!), from Delhi. Again! I met him during the 2010 STC conference in Delhi and was amazed at how he manages his disabilities. I’m still inspired. And the lack of sight is not his only handicap. He’s got the use of only one hand and it’s incredible what he’s done with that. He doesn’t even use a cane. I did try to warn him every time we were nearing a flight of stairs, but soon realized that I didn’t have to do so. He walked a little behind me and sensed my movements (up or down) and just followed suit. He’s incredibly creative, extremely knowledgable and articulates like a dream. Now add the sense of humor. On this trip, in addition to attending the conference, he’s working with an entrepreneur in Bangalore to build software that converts visual information to sound solution. He showed me his glasses that come equipped with a camera and earphones. Plugging this into a laptop allows him to ‘hear’ what he does not see. Images as seen by the camera are converted to sound on the laptop and then played back to him via the earphones. He's described this in a couple of blog posts you can access from his Linkedin profile above. But wow! You should see him handle his phone. He’s got an app that reads stuff out to him as he presses each button on his phone. He just holds it to his ear and thumbs a few keys. And he’s so efficient that he had already saved my number along with my name before I could even unlock my phone!
Adobe made selecting a track easy for those who seemed to have an overdose of tools. The panel discussion moderated by Francisco ran to a packed audience. Nobody knew what the topic was. But everyone believed Francisco would ask some uncomfortable questions. But he didn’t. However, he may have made some folks in the audience squirm. Lesson learned: Wait for the mike, however loud you may be. Especially when Francisco is moderating. Don’t say you are loud enough. Or you’ll end up hearing comments like “Poor husband”!
On hindsight, some of the members of the panel could have been selected with a little more care. Just like the questions. Because most of the answers were clichés. And you can’t blame the moderator for that. Some of the questions discussed were
  • What skill-sets do you look for when you hire a writer
  • What advice would you give a new writer (By ‘new’ I mean still unpacked!)
  • Comments on the Job hopping trend
  • Smart work vs Hard work
  • 3 tips for managers
  • Team-players or individual contributors
It would have been an interesting exercise to crowd source questions BEFORE the event.
Chitra Udayakumar presented a session on improving end user documentation. This was focused on industrial automation.
  • The purpose of automation is to reduce human interaction and cost/li>
  • It’s widely done in precision industries that include chemicals, manufacturing, power plants, etc
  • Typical problems include inability to find specific information, difficulty finding relevant information quickly, inaccurate or missing information
  • Recommendations included conducting user behavior analysis, establish target users, efficient design, use of wikis, multimedia, documentation standards and custom support portals
  • Enabling search filters helps users get to relevant content easily
  • In addition to more visual and interactive content, augmented reality was identified as a future trend. See how BMW is using augmented reality. (Pranav mentioned that this reminded him of Google goggles.)
And then it was time for some minimalism from Indumathi :)
We looked at a definition, what it aimed to achieve, some principles and what was required for minimalism.
  • Emphasis is on doing rather than knowing
  • Provide context for information
  • Focus on problem solving
  • Ensure content is easily and quickly accessible
  • Benefits included lesser translation costs, consistent content that can be easily migrated to structured writing and less review time
  • Make use of what the user already knows
  • Use help from marketing and customer support
  • Explain the task, not the feature
  • Structure information, organize content
  • Use flow charts, images, videos
  • Define content standards and templates
  • Avoid using adjectives and adverbs. Ensure brevity
  • Use only one way to do a task, even if there were many ways.
  • (Alternate methods could be provided in troubleshooting content)
  • Ask yourself
    • Do you know the user’s objectives?
    • Can you understand what’s documented in the first reading?
    • Can you write it simpler?
    • Can you navigate to it easily?
  • Test Usability
  • It takes longer to write less (unless it has 20 pages!)
  • Focus on quality, not on quantity
Producing Role and Task based documentation was presented by IBM's Neeti Suktankar and Attaullah Syed.
  • They started with discussing why we need role and task based documentation.
  • Looked at the evolution of software and how it created today
  • From being developed in silos for a discrete set of users, it is now being integrated and used by different users who have different goals.
  • Users need documentation that addresses customer scenarios and that is role and task based
  • Place the user role at the center of documentation
  • Helps users with a starting point and is geared to learning and education, not just problem solving
  • User classification based on user goals
  • Derived from business scenarios
  • Make use of access levels and user capability
  • Map tasks to roles. Work with PM to identify roles, task flow
  • Do this as early in the development cycle
  • Each task must be separate, independent and have an owner
  • Each task must be linked to a stand alone help topic
  • At least 5 to 7 tasks are required to justify a workflow
I liked the example where users could determine what help document to see based on what certain criteria they could select. Example, to install a software, if you select the operating system, the database, etc, different documents are generated based on the selections you make.
Adriane's Thread for Content was the last session of the day. It was a well organized and presented paper by writers from Dell.
  • It started by a short animation to refresh writers about a story most of us had learned in school... and then feared dark rooms.
  • The main components of the story was then compared to different aspects of technical writing (Why they didn't compare the minotour to an SME, I'll never know)
  • The roll of thread turned out to be the style guide
  • Has the style guide evolved as fast and as frequently as the tools, process and deliverables in Technical communication?
  • One of the main challenges was that organizations followed different standards when it came to internal departments. Thus tech pubs was using a style guide that was not the same as that used by marketing or corporate communications
  • The team did a study on this and tried to get a global perspective by asking questions on Linkedin groups and to writers across the globe
  • A major disadvantage of archaic style guides was that the content became style guide centric instead of being user centric
  • On the other hand, new age style guides used consistent style across different channels and scenarios and helps maintain one brand voice
  • Emphasis on usable and brand conscious publication
  • Depending on how much time is available for a review, checklists must be prioritized.
  • It is always important to prioritize legal sanctity of a document (unless you aren't concerned about getting your ...well, let's just call it a certain part of the anatomy... sued!)
  • There are three levels of checks, integrity check, copy and style check and comprehensive check
  • Split your style guide into usable chunks for different documentation requirements
  • Maintain a glossary of accepted terms
  • Form a 'style board', on rotary ownership
  • Form a terminology review board that is separate from style board
And there was evening and there was morning - the first day.
(For the uninitiated, the last sentence is lifted directly out of the most printed book in history.)
Watch out for day 2's proceedings shortly. Especially, for news from China!

The Emperor's New Clothes

What do you get when you have 593 years of work experience, a lot of which is as a manager? It’s the TC World Executive Conference!

Oh the title got your attention? Mission accomplished! Let's see if you can figure out why it's titled like that.
We’ve always had management tracks in most documentation conferences, and we’ll always have them. But here was an attempt to organize a conference focused only on managers in technical communication. And did it work? Well the testimonies at the end of the program sounded positive. This is not a new concept, at least to me. Triumph India had a similar program that they used to organize where their managers and other managers from their clientele would meet to discuss Tech Comm topics, or listen to a specially invited speaker. Of course this was on a much smaller scale, but it was fairly regular and yeah... sooo long ago.

Let’s start with what I thought was the best session of the day. It was an Innovation workshop... on steroids. With an almost lethal sense of humor, he’s often left detractors red faced, even before they knew what was happening. He's extremely sharp, thinks really fast and has an answer for almost anything. He’s now a consultant in gamification. He’s also doing something creative in the headhunting business.
Now imagine the same Edwin Skau on steroids. Literally. (He has some health issues for which he’s being treated with steroids.) You decide if that was good news for us or not.
If you've not heard of gamification before, here are a couple of really good videos that could give you an idea. The Ananth Pai video is brilliant and really inspiring.
Very rarely do you come across a presenter who starts his presentation by strumming a guitar. But that is how this workshop started.  Edwin strumming the guitar and the audience being made to chant "dum dum dum". This soon became "la la la.." because, as he put it, some people were taking things personally! I wish they allowed him time to complete the workshop. He had to pretty much stop abruptly, as we ran out of time. But not before I managed to jot down a few things.

  • One of the aspects about creativity is that you need to have time for it. Pressure doesn't bring out the most creative solutions. In pressure situations, the intent is always to somehow get the stuff out of the door.  Some of the folks in the audience disagreed and said they knew of situations where people had come up with creative solutions when under pressure. But I tend to agree with Edwin on his view point. The argument in this case would be to give the same people some more time. Would they come up with a better solution? The answer is usually yes. “It could have been better if I had a little more time”. “I could have done this also if I could think clearly….” , “Looking back, since the pressure to deliver is over, here’s what I would have done…” We’ve heard these comments over and over again.
  • Other aspects to be considered when speaking about creativity is that there's always a beginning and an end, there should be sufficient time, must involve risk, must be fun and must have wins.
  • Everyone is creative. Look at the excuses people come up with when work is not done, was his argument. I don't agree with this view. Can everyone be an Edwin? In the right circumstances maybe? But I’m sure we’ve all got at least one person in mind who could easily disprove this. It’s like saying all people are beautiful and ugliness is a myth :)
  • How do you measure creativity? Organizations often end up measuring activity instead of impact.
  • Some ways of measuring creativity include identifying value added, problems solved or revenue generated.
  • It’s important to redefine an issue before you attempt to think of a creative solution
  • There's more, but I was so fascinated that I stopped taking notes! Besides, he didn't complete the presentation. So I'm hanging on for his presentation, just like you.

Sarah O Keefe spoke to us from the US. She manages a company called Scriptonium. Here are some notes from her Webmeeting.
  • She talked about how technical communication could not only save costs but also add revenue and be considered a business asset.
  • She stressed on the importance of showing value to get funding for any initiative. She took the example of how a small script could shave off a couple of hours of writing time and how to present this data as a business case. This cumulative time saved over a week or month when considered with the rate of pay per hour, adds up to some number. It's now easier to show value as the savings of a 100 dollar script now compares with several hundred dollars worth of writer time. No brainer.
  • She  then took us through some common reasons for documentation that could be used to build a business case. 
  • Sarah then talked about some myths when it comes to bad documentation.
  • Bad documentation also resulted in
    • Higher call volumes to customer support
    • Product returns, lost sales
    • Contradictions to marketing literature
    • Regulatory delays, legal issues
    • Huge globalization and localization costs
    • Content duplication
  • Efficient content development can be discussed under reusing content, localization and formatting and production
  • 6 to 20% of revenue is spent on support. This number is larger for smaller organizations
  • Companies pay $6 to $36 per transaction of customer support
  • Obstacles that hinder efficient phone support
    • Time to load (Large PDFs are bad. Seriously!)
    • Local knowledge bases that don't have the official and most updated information
    • Conflicting information from customer support that does not match the documentation
  • Premium products must also have premium documentation.
  • If you are modularizing content for reuse, as a thumb rule, copy paste is a bad idea
  • Tech communication can support marketing with by creating the technical part of the content
  • We can also increase product visibility and help build user communities
  • Content must not only be searchable, but also findable. SEO ensures content appears at the top of your search results
  • Content must also be discoverable. It’s a futile exercise to hide your content and not make it accessible to Google because you are scared that the competition will steal your ideas. Sarah was convinced that the competition already had all the information they wanted!
  •, has several case studies and sample cost calculations.
Tony Self, who is also called Dr DITA talked to us from Australia. He spoke about DITA adoption and best practices. This was also a Webmeeting.
  • It’s not a good idea to port legacy content as is. Trying to do so is like putting lipstick on a pig! And we weren’t talking about Babe here.
  • It makes more sense to start from scratch.
  • Importance of fidelity and ability to curate content when it comes to DITA
  • Everyone needn’t adopt DITA. It doesn’t make sense to blindly adopt DITA. You need a strong business case to do so
  • Allows writers to focus on the content as it is separated from format
  • Important to understand what can go wrong during DITA adoption
  • Important to establish metrics to measure progress
  • Develop a strategy for DITA
  • Discussed case studies from various companies that have adopted DITA and have had varying levels of success.
  • Implement in a phased manner. Writing – Design – Assembly – Publication
  • New skills required when moving to DITA includes modular writing, topic based writing, adding metadata, writing to a specific audience at a micro level
  • Tony urged the audience to join the DITA Linkedin group, attend conferences and read several white papers on DITA
Kapil Verma, a product manager from Adobe, also used the webinar route to speak to us. He shared several interesting statistics on how structured authoring has improved documentation
  • Structured authoring has increased reuse in content in some companies by 10 to 15 %. In other companies, reuse is as high as 65 to 90%.
  • Time spent on fixing formatting issues has reduced between 30 and 75%. This enables authors to focus on the content.
  • Errors have reduced by as much as 34%
  • Time to market now takes 40% less time
  • Content can be easily ported to multiple output formats
  • He talked about how Ipads are now being used by pilots to access documentation and how that changes delivery for tech communication
  • It’s not just aerospace, but the mobile trend is now embraced in the telecom, energy and other domains.
  • More statistics on the use of Rich Media
    • 60% of users use images / vector art
    • 40% of use videos
    • 33% use interactive hot spot linked images
    • 18% use some form of audio files
    • 11% use 3D graphics
  • Kapil stressed on the economic condition and the increasing pressure to do more with less.
  • Statistics on collaboration
    • There are about 230 million tweets per hour
    • Facebook status updates add up to about 30 billion in a month
    • 48 hrs of video are uploaded to Youtube per minute!
    • Wikipedia has 3.5 million articles to date
Sandhya Prasad conducted workshops on setting up a documentation department and on quality concerns in Documentation, well mostly on the former. The audience was randomly split into groups and each group was asked to discuss one of the following topics.
  • Strategy
  • Hiring
  • Training
  • Operations
  • Credibility
  • Stakeholders
  • Team Building
  • Retention
Each team had to discuss challenges with respect to the assigned topic and then come up with best practices. We had to list down our findings on charts and hang them on the wall. You’ll notice that there are 2 charts on strategy and none on Retention. That probably explains why retention is a problem!
Pardon the poor quality, but here is a link to pictures of the charts.
We then had to present the best practice creatively using a skit or a song or whatever we could think got the message across. Boy, was this fun! While one team performed a jingle, the rest were all short skits. We do have some good actors too!
The final event was a Panel discussion. And this is probably where the emperor’s new clothes come in. Everyone knows this, but too much of emphasis is placed on a title. Does it really take a director to provide direction? Sometimes it’s just a title! Some may have earned it, others are still in the process of earning it. Why attribute leadership and the ability to provide direction, to a position? There are so many folks who have never been a director, but could provide much more inspiring insights. Edwin did briefly touch upon the way titles are misused. Personally, I would have preferred allowing Edwin the extra time required to complete his presentation.
But let's look at the discussion. The panel comprised of Directors from Dell, Alcatel Lucent, EMC2, Vestas and SAP. Some of the points discussed are listed below
  • Is the documentation industry in India facing quality issues? Most of the panel felt that this is not entirely true. However, they agreed that not everything can be defended.
  • Some of the quality issues were attributed to unrealistic expectations and ‘offshore politics’.
  • Some members of the panel felt that customers value accuracy of technical information more than perfectly written English
  • Discussed patents filed by writers in various organizations
  • Importance of succession planning
  • Managing employee expectations and successful experiments in relocating writers across the globe.
  • Challenges faced include meeting employee expectations
  • One of the panelists likened the trend of job hopping to employees treating an organization as a transit lounge!
There's also a lot to look forward to in February when the main TC world conference is being planned. Since a majority of tech writers are women, there are plans to set up a day care for kids so that the Saturday event attracts more women.
The men can just hope that the following year, they'll plan something for the wives too!
And if that happens, please remember to ask for identification!