Journal

news and resources for technical writing, information design and brand promotion

Archive for the ‘Technical Writing’ Category

1. Casting a consumer magic

   April 13, 2011. No comments.

   Many of us wonder how brands are coming up with so creative marketing campaigns – making their target audience jump from the seat and get in action. We can see some top advertising trends  being done in 2010 with a lot of innovation involved. So what is it that really sets fire in a marketing campaign and at same time, everyone gets some benefit out of it. campaigns become powerful when designed on better user experience.

   I won’t bind user experience with just software or cool Apple devices, but with anything that lets everyone make most of anything a business owner has to offer its consumers. So back to campaigns, QR codes are a new way into engage user and get online and offline experiences. As a matter of fact, they offer even more on both consumer and business ends. Smart marketers make sure they put in some nice piece of information when a user scans the QR code from mobile. Better experiences don’t just related to scanning codes but a powerful campaign would involve leveraging all platforms in a synchronized way – traditional as well as new digital mediums. A welcome Facebook page offers some discounts, group discounts or local deals websites, collaborative offers, promo videos on YouTube and what not :).

   Here the first implementation of QR codes is a public awareness message. Like, a QR code with few instructions and how to scan – I recommend using BeeTag and Kaywa; as they support most of the mobile phones with camera. Seems like a hassle doesn’t it? Going through the download of a reader from native app stores is a single exercise making the next moves smooth and easy. Once this public campaign gets a good footprint, the job is done for many businesses. Then you go posting QR codes on store windows, street lamps, magazines, flyers, coupons, event tickets and where not. It’s easy said than done. As discussed earlier, a marketing campaign today needs to be coherent. Let’s play QR codes!

   

    

   

    

2. selling solutions – not boxes

   February 9, 2011. One comment.

   I happened to be at a furnishing store and checked out new furniture designs. Initially, I felt lost in picking out some nice trendy designs. I was looking at various aspects like design, size, wood, portability, durability and lot more. And then out of nowhere comes the salesman with a worn out catalog. Nothing really seemed appealing to my perfectionist eyes since spending this lot of money needs justification :). While I flipped pages over and over looking for an optimum solution, the lightning struck – my personalized bed. I was precisely looking for a customized solution and not a boxed product.

   Likewise, we can relate such customized solutions to open ended business services. Services turned solutions are the way consumers / clients are expecting from businesses. Merging a couple of features from different samples, I got a design matching  the interior theme at my home while also gratifying the aesthetics sense.  I could’ve even ask for embossing my name on each piece, but let’s just keep it here. Similarly, we keep ourselves in the paradigm of successful product selling rather considering the customer experience in mind. Even then, companies hardly pay attention to the end user experience of the boxes sold out. The customer experience remains ignored while dynamic businesses keep bringing better services turned business solutions to their customers.

   Implying expertise and skills in a unique market or improving user experience in particular business domain is what is the trend now and we can see so many companies imparting this concept.  The ultimate focus now remains to optimize the end user experience. In our area of expertise, the faith lies in understanding the pain points of customer to bring quality, retention and satisfaction – resulting in a partner program initiative. Proper requirement gathering, analysis and elicitation eventually lead to closely matching what customer wants. In my case above, the most amazing furnishing experience at home.

   New trends are pushing companies to be more engaged with customer to get feedback on user experience. Crowd-sourcing, real-time collaboration and social media engagement platforms are bringing more customer-centric solutions to our agendas while being the most trusted partner of our customers.

   

    

3. Know thy users!

   December 30, 2010. No comments.

   “The user is NOT a lower life form” – Ken Becker

   

    

4. What users want?

   December 16, 2010. One comment.

   “What users want is convenience and results.” - Jef Raskin

   

    

5. Free MadCap Demos & Trainings

   December 16, 2010. No comments.

   If you are like me – addicted to MadCap’s products, or are just curious about the cool things these guys are developing, here is your chance to get free product demos, join training sessions, and get valuable tips on content development and working in collaboration from industry leaders at 2011 MadCap Roadshow in Long Beach, CA.

   

   The event coincides with Writers UA Conference (March 13^th – March 16^th). So if you are planning to attend the conference, do stop by at MadCap’s show. This full day event would cover various topics including authoring techniques, working in collaboration, content management, use of CSS, and guest presentations from technical communication experts in five sessions.

   Entry to the show is FREE, if you sign up now.

   

    

6. In Defense of Technical Writing

   November 30, 2010. 3 comments.

   Recently, Ellis Pratt of cherryleaf.com shared his thoughts on David Black’s (of Nokia) idea of products that are so intuitive and users so literate that nobody would require user manuals to understand new technologies and products.  This suggests that technical writers would not be needed to produce user documentation. Ellis argued that the idea of products so intuitive that anybody can understand is like a product that sells itself. This further suggests that there would be no need to market new technology (people would just acquire it). Of course, this does not convince.

   We would always need people to promote and explain new ideas and technologies. We may not need education for products that we use frequently on daily basis such as cellular phones or portable music players. However, people would always need some sort of education to get comfortable with enterprise applications, sophisticated tools, gadgets, hardware, and software products.

   Ellis believes people would always have appetite for simple explanations of complex tasks. This idea inspired me to conduct a study within my professional network. I asked my friends and colleagues whether they read the user manual that came with their favorite gadget; the result was an eye-opener. A majority of participants (40%) told that they read the manual first. A good number of people (35%) said that they just started using and learning the device. Only 10% participants did not notice that the product came with a manual whereas 15% consulted the documentation when they were stuck.

   This suggests that at least 55% of users read the documentation to understand their favorite products. So I can assume that the number of people consulting user documentation would be higher for products that are complex or essential for performing day-to-day business.

   

   Results of my study can be accessed at: http://polls.linkedin.com/poll-results/111480/totqn

   

    

7. Publish Print Friendly Documents Online

   November 10, 2010. No comments.

   Technical Writers, today, write for various forums (users community, wikis, knowledgebase portals, blogs etc.) and publish content in multiple formats (printable documents, XML, HTML etc.). When content is distributed across multiple forums and location, it becomes difficult to keep the text updated at all places. On the flip side, content available in different formats and at multiples places is readily accessible. You can easily refer to an online article, blog or forum. For a technical writer, this makes life easy especially if you are often asked to produce documents at the eleventh hour. There are a number of smart free tools that you can use to process online content into printable documents in almost no time. One smart tool is PrintFriendly.

   

   PrintFriendly is a free online service that allows you to convert web pages into print  friendly documents with all margin and spacing matters taken care of. All you have to provide is URL of the page that contains desired content. It can be a blog post, an online web page, link to a discussion etc. Print Friendly processes the content and allows you to send the document directly to the printer or publish it as a PDF file that you can print later. Before printing, you can review and edit contents of the document. You can also use PrintFriendly to save online articles in PDF format for archiving purpose or to print and read later.

   

   

    

8. Questions of an Editor

   November 6, 2010. No comments.

   At one point we all agree that writing is still a complex process. Don’t agree? Well it requires doing necessary research, analyzing audience and paying so much attention to the document structure (images, steps, indexes, page setup etc.). So a writer can get distracted.

   Editing plays a role here as an opportunity – allowing writer to emphasis on the quality of both writing and presentation. So its like pulling away from research and writing towards better user understanding,  meeting expectations and content quality. Though Editing comes at the end and right before handing over the project. Let’s look at Editorial types (and questions asked) that an editor would look into a document:

   • Suitability for audience and purpose – Does this document respond adequately to the task assigned?
   • Completeness and Accuracy – Are all the required parts included? Is the content accurate and adequately developed for the intended audience? Do the content and discussion of it respect ethics?
   • Organization and consistency – Does the sequence of information reveal the relationship of ideas? Are related parts treated in consistent ways?
   • Visual design and usability – Will page or screen layout, illustrations, and searching devices (table of contents, headings, menu) help readers find what they need? Does the visual design enhance interpretation of content?
   • Style – Do sentence structures and word choices clarify meaning? Is the tone right for the audience?
   • Correctness of grammar, punctuation, and spelling; consistency – Do grammar, punctuation, and spelling conform to conventions? Are capitalization, use of numbers, dates, and abbreviations treated consistently?

   Reference  for Editorial Types: Technical Communication, Page 261, Second Edition, McGraw-Hill Higher Education

   

   
   

   

    

9. TLDR.it – Free, Online Content Summary Generator

   November 1, 2010. 6 comments.

   Are you are a writer or a researcher and read a lot of content? Do you receive a lot of news, feeds and documents to scan and comment daily? Got a long report to summarize? If yes, give the stuff to tldr.it to scan and filter key points. The online service can scan and summarize articles, newspapers, blog posts, RSS feed and even PDF documents. The result is concise summary of key points in three formats: short, medium and long.

   

   The service is free to use and support content in English language only. Try yourself and see how accurate it is.

   

    

10. Being Creative in Writing Technically

    October 31, 2010. No comments.

    I was just thinking how journalism writing is done and what I need to consider. Just a simple thought

    crossed my mind that I should be able to read my article again with the same interest while not wishing

    to print and throw in the bin. With the similar objective, writers try best to be effective and clear, but

    the problem lays the same as if they are really communicating meaningful for their right audience.

    Considering the technical communication field, it has mostly been associated in the past with jargon

    based writing – in a form only understood by technical people and experts of a certain field. The

    information would be simply too accurate to comprehend by a layman. It makes sense to define and

    describe an activity or a process which is not based on an assumption. Likewise, a writer’s personal

    experience matters the most, which adds creativity and life in a piece of information.

    

    The technique of creative technical writing lies beyond being neutral and objective, whether a

    writer is very careful in choosing words or is being precise in writing clearly. To eliminate the need of

    interpretation or a dictionary to avoid confusion, some fields have developed a standard of key terms

    that translate some words more effectively and for the right audience. Here, a UK based organization

    – Plain Language Commission – is helping writers to use plain English language to develop content

    for web and print material. However; there is still some part of interpretation left to be done in some

    specific industries.

    

    So they resolve this by having specialized individuals who transform information in a language, which is more readable for people who work in the respective companies and organizations. The moment writers start defining and describing information in plain language, the reader’s job become easy and topics become approachable. What’s more, this reduces error and confusion while at the same time makes a user reach a goal more effectively and with efficiency. Again, writer should keep in mind that not always is any information is so meaningful to all types of audiences. However, a writer must always keep in mind the reader’s adaptability to comprehend the words. I’ll wind up with an example of definition, “light pen – A light-sensitive input device used to select an entry or indicate position” (Szymanski et al., 738). Now a teacher can work on this definition to make students understand in one go.

    Reference: Plain Language Commission

    

     

11. Working in the Cloud

    October 29, 2010. 3 comments.

    These days, I spend most of my time working in a cloud where I store most of my data and collaborate with my co-workers. More precisely, I work in a data cloud not ‘the cloud’, which is, accumulated mass of evaporated water :)

    If you are not familiar with data cloud, it is a space where all of your required software and services are running. You just need a personal computer and Internet connection to use these services – no additional hardware, software or IT infrastructure required. By using cloud-based services, you can do various tasks such as: creating and sharing office documents with your co-workers, use whiteboards, mind maps and many other tools to collaborate on different projects with your colleagues etc.

    

    Cloud computing has a lot to offer to writers and researchers who work in collaboration. There are a number of tools that writers and researchers can use to:

    • Create a virtual workspace where people from diverse locations can collaborate on a single project
    • Create, access and share documents from their virtual workspace in the cloud
    • Use almost all features for creating, formatting, editing and designing documents in multiple formats that most desktop applications offer

    Here is a quick round-up of some popular and useful tool for working on collaboration:

    Google Docs

    My foremost choice! Google Docs is simple, fast and free. Google Docs offer comprehensive set of features that you need to create, share and manage documents, spreadsheets, presentations, surveys, forms etc. You can also collaborate in real-time and track history of documents.

    Adobe Buzzword

    Robust and powerful tool for writing documents, reports, proposals etc. Buzzword also allows you to manage multiple versions of a document, collaborate with as many people as you want, edit images and view real-time updates from contributors.

    Advance users can use Adobe Buzzword with:

    • Adobe ConnectNow to organize online meetings and conferences to discuss ideas
    • File Organizer to upload and share files and covert documents to PDF
    • Adobe Tables to create, edit and share online spreadsheets
    • Adobe Presentation to use powerful features of designing rich presentations
    • Adobe Workspaces to create a virtual workspace for team

    

    Microsoft Office Web Apps

    Free web-based version of Microsoft’s popular office applications. The suite includes Microsoft Word, Microsoft Excel, Microsoft PowerPoint and Microsoft OneNote. These services are available via Docs.com and SkyDrive.

    Writeboard

    Free collaboration tool by 37signals. Writeboard is complete free and can be used to create documents, track version history, and compare and rollback changes. Writeboard can be used in collaboration with Basecamp for an effective project management and collaboration experience.

    

    Gobby

    Free collaborative writing tool with many impressive features including:

    • Realtime Collaboration
    • Tracked Changes
    • Chat
    • Password protected sessions
    • Drag-and-drop environment for importing documents
    • Syntax highlighting for most programming languages

    Google Wave

    Since it is from Google, it is simple, free and fast. Google Wave can be used to organize web meetings and project collaboration. People are using Wave in creative ways in journalism, creative arts, education and many other industries.

    Zoho Writer

    Another free tool for online word processing. Zoho Writer comes with built-in templates, collaboration options, offline support and facility to import or export documents.

    ThinkFree

    Online services that provides free web-based office applications with 1 GB of online storage capacity. Documents created with ThinkFree can be accessed in smart phone built on Android, iPhone, and Windows Mobile.

    

    

     

12. Favorites Forever

    October 20, 2010. No comments.

    Do you have hundreds of favorite websites bookmarked in your browser or piles of notes, documents, photos, ideas and emails saved in your personal computer? How do you filter and retrieve this information?

    I use Evernote to clip, tag and archive everything noteworthy – online articles, references, blog posts, tweets, mind maps etc. The data is synchronized with my online Evernote account allowing me to search my organized favorites anytime and anywhere. No more broken links (bookmarked pages that do not exist now), no lost files, and no pile of unorganized information.

    
    If you are a technical writer and refer to bookmarked websites and topics frequently, use Evernote. It allows you to clip information, dump it in your Evernote notebook, and tag it with keywords for future reference. Dumping and retrieving data takes just 15 seconds. You can also use Evernote to save frequently used information so that it is easier to find and reuse contents when your are offline or away from your computer.

    Guy Kawasaki has suggested a number of ways to use Evernote and ease your life. I use it to:

    • Clip information – I save my favorite tweets, blog posts and articles in Evernote; this allows me to find and reuse contents easily.
    • Write and save notes in Evernote – No need to store papers or save text files and remember their names
    • Take picture notes – While on the go, I take pictures of anything noteworthy with my cell phone and then tag and dump photographs in Evernote.
    • Save Attachments – I forward email attachments to my Evernote account for safekeeping; because data in synchronized with my online account, I can access these files from any computer online.
    • Save Contacts – I do not carry piles of business cards. I photograph, tag and dump them. Evernote recognizes text so I sift through the data to find and save contacts later.

    Interesting? How would you use Evernote? May be you can use it as virtual whiteboard to collaborate with your team members, as ‘mood board’ to collect customer’s feedback or as personal gallery to store inspiring designs.

    

     

13. The Terminology Cloud

    October 18, 2010. No comments.

    Technical Writers often have to use, explain or refer to terms in technical documents. Most technical documents contain glossary or a list of terms used in the document. Usually, tech writers in a company compile and share a list of commonly used terms related to their domain or business. This is a good idea! It ensures that all definitions are consistent across various documents, white papers, website content, and other communications by the company. Based on the same concept, TermWiki has compiled a huge list of terms that writers can consult in order to verify or find meanings of almost any term.

    

    The ever-growing list of terms at TermWiki is fed by a large number of contributors that provide definitions and translation of terms belonging to almost every industry including software, banking, sports, healthcare etc. Translations are available in English, Japanese, Russian, Korean and many other languages.

    

     

14. Breaking into Technical Writing

    October 18, 2010. No comments.

    Are you an aspiring technical writer wondering how to break into technical writing, what tools to master to become a successful technical writer or what are the career paths for technical writers? Tom Johnson has recently delivered a comprehensive presentation at BYU Pre-Professional Writer’s Conference to answer all of these questions. Tom breaks many mis-perceptions about technical writing and explains that technical writing is not just writing routine instructions (click this, select that etc.), it is much more than that. Most experienced technical writers evolve as content managers, marketing communication specialist, usability experts, information designers, business analysts etc.

    

    He further describes a typical day of a technical writer at work to prove that besides writing and publishing content, technical writers contribute to a lot of other activities as well. Typically, a technical writer attends meetings, reviews prototypes and submits feedback, tests instructions and logs issues, analyzes technical specifications and updates information.

    Tom also advises that there are a number of entry paths to this profession. Technical Writers usually have diverse professional and academic backgrounds such as IT, software engineering, research & development, language and linguistics, media etc.

    Follow this link for full story.

    

     

15. On Clarity

    October 16, 2010. No comments.

    “Those who write clearly have readers, those who write obscurely have commentators.” – Albert Camus

    

     

16. Gaining reader’s attention

    October 12, 2010. No comments.

    Once at a crowded shoe store, a mother was constantly advising her 4 year old to “don’t touch it son” – “don’t do it” to keep him away from the window shelves, but he would still drop a shoe once in a while. Pretty amused at how directions are given and still unattended, this rushed in a feeling when we see writers keep signalling to the users with precautions in their manuals. A writer would test a product and write on it. Some are concerned to keep the users away from danger and loss, other’s don’t. I do!

    As technical communication moves two dimensional – users and topics – writers still keep a close eye to the user’s environment and behaviors. A close study on Wikipedia reveals some insights on this applied science of user behavioral analysis. In a broader prospective, it’s a common practice we tend to observe behavior of others and ourselves when interacting with an interface. Lot of people panic at ATM machines not knowing what to press or where to touch and keeping the machine occupied for several minutes. I would suggest putting few lines of instructions alongside for a novice. So as not to insert cash where one has to withdraw.

    Writers need to ensure that user is comfortable in understanding the normal instructions in a manual to those of the precautions – Notes, Tips, Warnings. Making a document stand out with handy tips does make a difference to a plain manual carrying feudalism. Useful notes let the user feel comfortable with less anxiety of using controls in a different way, as to just pressing in a wrong combination – like for a video game console. Some real case scenarios and examples are also a nice way to show how a process can be done in a certain way.

    Users are an indirect ROI to the manuals, which become an important part of any product selling.

    

     

17. Writing Technically

    October 11, 2010. No comments.

    Technical Writing is usually related to the IT profession. Strange! What if a person is writing Getting Started Guides for BMW Mini, a person writing Standard Operating Procedures (SOPs) for cargo handlers, or a person writing instructions for website visitors?

    Exploring the dashboard of your car would reveal a handy manual that is usually not given much attention. God knows the reasons and we (authors) intentionally don’t :). Automobile manufacturers have good intentions too to include a nice manual in your car’s accessories. Same goes for your washing machine, cellular phone, folded beds and a lot more things around you. All of these things come with brief or comprehensive guides. These are written by technical writers.

    Technical Writers work for various different industries ranging from pharmaceuticals to defense and software development to manufacturing. With the diversity in industry, the scope of technical writers’ work has expanded beyond just user manuals and online help. They create and manage wikis, blogs, video tutorials, illustrations, demos, training materials and a lot of other stuff.

    While industry and deliverables of technical writers are diverse, the basic principle of technical writing remains the same - analyzing audience and writing plain language to explain technical information to non-technical audience. However, the tools and techniques do vary. Technical Writers, today, use a number of techniques such as localization, single source authoring, collaborative writing etc. Imagine a French owner of an Audi reading online content written in French and tailored to the specific model and a German owner reading customized content in German and written specifically to the model that he owns. This asks for a lot of content development, customization and optimization – all done by technical writers and content managers.

    Convinced? The next time you struggle with your new vacuum cleaner, just pick up the manual that came with your machine and see how easily you can take out the dust bag, clean it, and then fix it back.

    

     

18. How to conduct a 5-seconds usability test?

    October 6, 2010. No comments.

    Are you an information designer or a technical writer experimenting with a new information portal, website design, technical illustration, product interface or a new layout of online help document? If yes, I suggest that you put yourself in the shoes of a novice user and test your design for its usability. Imagine how an average user would try to understand your new design.

    An easy way to analyze your design is to conduct a usability and memory test. Grab a screenshot of your new design/layout, show it to your friend (an average user) for a few seconds and then ask him what items he can recall. If your friend can understand the purpose of your design and recall core components, your design is successful.

    If you want to conduct a usability/memory test at large scale, try Clue. It creates online memory tests that you can share with your friends via facebook, twitter and email.

    It also lets you analyze test results to:

    • Understand how users interact with your online contents, data, or website design
    • Test how many people can find the ‘Buy Now’, ‘FAQs’, ‘Help’, or ‘Products’ links
    • Make sure that your product or website explains it purpose to average users
    • Get ideas for design improvements

    Creating a usability/memory test with Clue is simple and fast. Try it today!

    

     

19. Are you ready for real-time collaborative writing?

    October 6, 2010. One comment.

    Though writing in collaboration with multiple teams and contributors has been in practice for quite some time now, but the tools and techniques for creating collaborative environment have started gaining popularity and wide-spread implementation recently. Technical Writers are now adopting this new paradigm and learning to work in virtual teams where people from multiple locations, different departments and various hierarchies can work together. This saves a lot of time and effort as compared to traditional writing, review and editing process.

    Google is one of the early providers of online collaborative writing services via Google Docs. The latest updates have made Google Docs a more convenient platform for collaborative writing. Now you can do a lot with your documents in an online, realtime environment from anywhere, anytime. The latest enhancements in Google Docs include:

    • Real-time collaborative highlighting in documents
    • Document translation
    • Auto-linking in documents
    • More page sizes
    • Add words to dictionary
    • Draggable rows and columns in document tables
    • Optical character recognition (OCR) to convert PDF or image to text
    • Themes, Improved Drawing Tools, Format Painter for spread sheets… and a lot more.

    If you are a technical writer and have not worked in collaborative writing environments yet, I suggest that you start exploring it today? Start with Google Docs; it is free!

    

     

20. Writing for Non-Technical Users

    October 5, 2010. No comments.

    No matter how experienced technical writer you are, you always have to revise your documents and tune them for the ‘real people’. By real people, I mean, end-users (not the product developers, QA guys or sales people) who interface with your product in many different ways in many unexpected environments. Writing for the real people involves a thoughtful strategy: analyzing the audience, selecting the right format, and carefully structuring the content.

    Andy Brice, in this article, has highlighted 10 things that an average end user does not understand about software products. If you are a technical writer or a usability engineer, I suggest that you read this article and make sure that your documents address these 10 issues.