Context Strategy

Posted on February 21, 2011 by Bill

Here are my Top 10 tips about how we talk about the design of the user experience. We often focus on the user interface and forget about the overall experience. For my work on Web applications, which are different from Web sites, it’s not so much about the content strategy but the context strategy, because we need to consider the user’s process, their business process, their overall business context.

1. Everyone is an expert of the UI – it doesn’t take an expert to know when a UI is bad. The challenge isn’t to know when a UI is bad; the challenge is to have the resources to fix it in a timely manner or at least to capture the feedback you are getting.

2. It is easy to point to the UI or UX experts but it is not so easy to have a UX expert on the team and give them say in the design. For a team of developer who are used to working on their own, the designer or other member need to be integrated with the team with equal status.

3. The user experience isn’t just the UI. That is so obvious and so easily overlooked. There is a difference between UI design and UX design.

4. The software isn’t finished when the developers can get it to work on their machines; the product works when the user uses it on their machine in their process when they want to.

5. Web apps (web applications) are not web sites. There is a vast difference between deploying a Web application at a customer’s site than posting a Web site on our own servers.

6. Web Apps are not desktop apps. There is a vast difference between allowing users to run an application on a Web server and allowing them to run an application on a desktop computer. But there is also a difference between how a Web application is deployed and used than how a desktop application is installed and used.

7. You can create all the design patterns and style guides that you want, but if the developers do not follow them, then you are not going to get the consistency you want.

Okay, when I get three more good ones from your comments, I will add them to my list and round it out to ten. Come on, give me some good ones.

Posted in User Experience, Web Applications | Tagged , , , | 1 Comment

Information Architecture in 3-D

Posted on February 11, 2011 by Bill

Information architects don’t primarily ‘architect’ information per se. We about planning, design and oversight of the construction of the environment in which users (human and otherwise) can deliver, access, use, and maintain (and otherwise interact with) information. It’s about optimizing and maximizing the interaction with information. It’s not just creating a document or making a web site. It’s about figuring out and implementing the best way for users to easily and timely get the information they need when they need it in whatever virtual space or social arena online that makes sense.

The definitions of Information Architecture that Google has compiled shows how limited most of the definitions are: they limit it to the Web and they limit it to information, not the information space.

The analogy with building architects is helpful, because they work with spaces, they work with multiple dimensions. Where they work mainly with physical building in public spaces, information architects can be said to work mainly with virtual information spaces for (but not limited to) corporate solutions. The aspect that we work in multiple (at least 3) dimensions is something I’m going to write more about. 3-D is not just for the movies.

Posted in Information Architecture, Practices | Tagged , , | Comments Off

Dim Sum and Then Some

Posted on December 12, 2010 by Bill

The STC Carolina Chapter did a great job of hosting the Best of Show judging at their most recent chapter meeting this past week. It was held in a restaurant called Dim Sum House and all fourteen of us judges sat around a long table and shared a little bit of everything. We each ordered different dishes and shared with each other, which is a perfect metaphor for the evening. We all shared the candidate entries for the Best of Show award, we all shared stories of our experiences judging in general, and we shared introductions about who we are and what we do for work and what we do with STC. We all brought something to the table. It was fun to spend time with fellow professionals in such a comfortable (and deliciously provided) setting. The food was delicious and just enough out of the ordinary. The candidate entries were each distinguished and just enough out of the ordinary. It’s one of those times when you feel proud to be a technical communicator and proud that there are others making some pretty significant advances in their work.

Posted in Blog, Profession, Professional Association | Tagged , , | 1 Comment

Judgment Day in STC Competition Land

Posted on December 5, 2010 by Bill

Yes, today was the last day for us judges (for the STC Carolina Chapter competition) to have our evaluation forms submitted. I got my forms in just in time and our team leader is probably glad that’s over with. I’m done with judging.

The Form of the Form
I joined a very respectable team of fellow judges and we really spent some time looking at our entries. Do you know what the average time a judge spends evaluating an entry for an STC competition? Well, I don’t know, but I know that I put at least a couple of hours per entry into this whole judging effort. It’s a demanding job that requires experience, a good eye, and articulation abilities that differ from our usual technical communication abilities. Offering both constructive criticism and positive feedback, we need to write our evaluations on particularly unfriendly forms. Several years ago we used forms that asked us to quantify (yes/no) whether an attribute of a good entry was met or not, and then total up the numbers to determine if the entry was worthy of an award. And oh, yes, we were supposed to add some additional comments that would be helpful. I guess a lot of judges were skimping on that last part, so STC decided to change the layout of the evaluation forms. Now, the form consists of rectangles of white space where you have to write comments about every attribute of an entry, which sounds great – lots of freedom to express yourself, but the problem is, who has the time to write complete sentences for 20 to 40 aspects of an entry? Now it takes longer and requires more thought to fill out the evaluation form. And this extra effort is expected from professionals who have seen their workload double and triple in their day job and who have less time to volunteer with STC. Shouldn’t the forms take less time to fill out now then previous years? And who came up with the word or phrase that appears in the otherwise empty box? What do these boxes even mean? Who designs these forms? Never mind. Let’s just say that I don’t think the change to the forms is an improvement.

New Evaluation Form Sample

New Evaluation Form Sample

Old Evaluation Form Sample

Old Evaluation Form Sample

Time is in Short Supply
I must say that it has been a learning experience for me, but it is not as fun as several years ago when I judged for a similar competition but under much different circumstances. Besides things being easier in the old days — when we didn’t have to wear so many hats at work, and your colleagues weren’t getting laid off or downsized, ah, the good old days, when STC was about twice the size that it is today, and there was no shortage of volunteers and professionals had time to meet for lunch or dinner or an evening meeting — but I digress, besides all that, there was value in evaluating each other’s work. Today, who has time to put into this archaic ritual? I mean, outside of STC judging, do people really still fill out boxes in Microsoft Word documents and attach those documents to emails anymore? I felt as if I had been transported back in time to the 1990s but without the luxury of time I had then. For some reason, this year, the entries didn’t get distributed until later than usual, and with the Thanksgiving holiday being more important these days with family time getting pressure from every side, we had very little time to look over our entries, evaluate them, and meet to decide about awards. I started to wonder why were using such old technology for evaluating entries. I mean, for all of STC, can’t someone just make an online web site so we can post our evaluations in the cloud?

Blurring Boundaries
And what IS an entry anyway these days? In the old days there were user manuals and there were sales data sheets. Now there is everything in between and documents that cross boundaries and content that does not even reside in a document. There is no separate printed versus online competition anymore and STC has changed the categories in a vain attempt to keep up with the kaleidoscope of content containers. So entries come in PDF files and I’m not sure if they are meant to be viewed online or read as a printed document. Entries are in this gray area between sales and engineering, between promotion and instruction. And what does “Informational” mean anyway? Isn’t that redundant for anything we do? Of course this blurring of categories is simply mirroring reality, but it poses the question of why we have categories at all. But there’s an even bigger question that comes to mind when one considers the technology of the entries and the technology behind competition judging.

Feedback is Essential, but When?
With so many forms of communication on the Web now, and so much communication happening instantly, who needs judging of entries? The question is – Is this form of peer review and feedback even useful these days? I mean, besides the great back-slapping that goes on as we award fellow professionals for their work, besides the chance to make ourselves feel important and honored, the main value from STC competitions has been the great feedback you get on your entry. And that feedback used to be very valuable before web site analytics came along, before server-based documentation included feedback forms, and before social media became available. Now there are so many forms of feedback that tie directly to the users of the content and that feedback can be collected in almost real-time, that I can’t imagine how useful my judging is if it takes months before the submitter receives the feedback from the judging. Hey, by that time, they are probably on to other projects, moved to other divisions of the company, working on the next generation product, or even looking for another job after being laid off from the one that involved them creating the entry. In an age where Whitney Quesenbery can do an online web site usability study where she remotely connect to my computer and see where I click in her Web site, who needs the delay or the anonymity of these old-fashioned judging events?

Yes, today’s the last day for me. That’s it for me. I don’t think I’ll be judging for STC anymore. I’ve done my time; I’ve judged several competitions now and it’s time to retire. Maybe it’s time to retire the whole notion of STC competitions.

Posted in Practices, Process, Professional Association | Tagged , , , , , , | 11 Comments

Ideas for Future Blog Posts

Posted on November 17, 2010 by Bill

I have several ideas swirling but none are complete enough to write a decent blog post on their own with thorough enough treatment, so I offer an abbreviated mention of these ideas with the hope that in the next little while they can be expanded upon. Feel free to give me feedback – which of these topics do you like, upon which of these topics should I expand, and on which of these topics can you offer me information. Look for more on these topics in the near future.

Documentation as Baseline
It seems that the first version of a product and it’s documentation become the baseline for future development. When requirements are asked for, reference is made to that documentation for that version of the product. When competitors want to develop a better product than their competition, they backward engineer the product or look at the documentation. “I want it to do what this does”. Or a testing team can turn to the user documentation as a way of seeing a list of features that must be tested. Or a training team can turn to the documentation and see what the product is supposed to do. To what extent is the treatment of Documentation as a Baseline appropriate.

Survey versus Social Media
Not that using an online survey is exclusive of using social media, but if an organization wants feedback from an audience or customer base, is a survey the best way to go or is using social media a better way. They are certainly different. Recently I received a survey from an organization with a list of questions. Wouldn’t it make more sense to keep those questions out in a more social place where constant feedback could be listened for, rather than taking a one-time snapshot of answers and basing decisions on those?

Welcoming Rick Sapir to the Game
Recently Rick Sapir reserved his domain name and launched his web site (www.ricksapir.com) and I wonder to what extent and at what rate we can include him in the game. He has begun to post content, but we need to interact with his site to get his visibility up. To what extent can he be more interactive and engaging? To what extent does the existing online community need to reach out and engage him? What responsibility does the community have for welcoming a new comer? In what ways can social media be used to go beyond simply posting content? Can we more automatically engage others, respond to their questions and needs, etc.?

Permanence of Online Content
One of the strengths of working online is that the content is there for you to access anytime and from anywhere. But that strength is also a weakness for social media. Sure I would like to post content and share with friends around the world, but once it is online, it can remain for a lot longer than the content of a normal conversation would. Not all kinds of human communication are going to work online especially if it cannot be erased. A whisper in a hallway has no equivalent online because the content is as visible and enduring as anything posted on a web page for customers.

Higher Order Analytics
I am sure someone is working on this but I have not read anything about this yet – it must be possible to do analytics on the run-of-the-mill analytics that companies do of their web site content. This meta-analytics can tell us which types of analytics are helpful or predictive of trends or indicative of success or whatever the goal is. And can you then do analytics on that order of analytics? Statistics of statistics has to take into account the degree of error involved. I’m sure analytics of analytics similarly has limits to its accuracy and precision but it still might be useful.

Posted in Future, Philosphy, Practices, Profession | Tagged , , , , , | 4 Comments

Valuing the Total Technical Writer

Posted on October 6, 2010 by Bill

Michael Harvey offers a good starting point for talking about marketable skills and business value in our profession. His latest article Timeless Skills for Technical Writers suggests that writing (or communicating) is our crucial skill. He starts with some good questions “What skills should technical communicators cultivate to ensure their market value? Is there a single set of skills that would weather whatever market and technological turbulence occurs?” But there is more to explore here and this is worth fleshing out a bit. So many people misunderstand what technical communication is, because they limit it to a subset of activities, and Michael Harvey’s article does not go far enough to clear this up. The truth is a bit deeper and more challenging and more fun. If you would like my advice, read on.

Everyone must write (or at least communicate)
The current business environment that expects all professionals at a given level to communicate should not be characterized as aiming for the lowest common denominator with the attitude that “Anyone can write.” Instead, business is aiming for the bottom line and a more accurate characterization would be that in the information age, “All must write.” It does not make sense for software companies or pharmaceutical manufacturers or any number of innovative start ups in the Research Triangle Park area to have only a limited number of staff who can communicate. Where we as full-time communicators can make a difference is by helping everyone in the organization communicate better. We can help with any number of these:

  • helping them write more clearly
  • directing them as to what document types can best contain the content
  • showing how to maximize content flow with process issues (including process documentation)
  • automating content development, presentation, delivery and maintenance

While I agree with Michael’s statement that “The ability to communicate clearly, correctly, conversationally, and concisely will never lose market value.”, I don’t think that thinking about a technical writer acting as an individual is the most helpful. That ability is valuable because everyone in the organization must be doing it effectively. And we must be doing it together. A better way to say this is that our skill set will not lose market value because “The job of a technical communicator (in partnership with all stakeholders in the conversation) is never done.”

Writing is not our only skill
Writing is not our only skill – it is only half of our job title and less than half of our skill set. Technical writing is not just writing. It is technical AND it is writing. We do not, like writers, have months to compose a manuscript. We do not have that kind of time to research a product or service and produce a user guide, or to implement a content management system, or to figure out social media for engaging with our customers. We do not have the luxury of sitting in our own room and writing, all alone and undisturbed. We must interact with all the stakeholders and make the subject matter expert’s “subject” real. We have milestones and deadlines. If we are ambitious, we find the bottlenecks and fix them; we write the topics that help the most; we talk to technical support to get the user’s perspective as well as talking to the subject matter expert. We develop style guidelines where they make sense to make everyone’s job easier. We do a range of tasks that help companies make money and engage customers. As Michael knows, many of us are not writing for the general public but a specific audience that requires content at a certain level of business context and technical knowledge. We work with a range of personnel and the task of communication is getting more social and more online.

Time(less) is money(less)
I disagree that our only timeless skill is writing. How we write and what we write will change over time. The business environment is changing and so should we. The only timeless skill in our profession is adapting or learning (and learning to change). There are no skills, like writing, that will keep you employed. Every company and every market has variations and you have to go with the flow. Within a company, I would recommend that you find out what that company prizes most highly and start writing about it. If it is product, then write about the product; if it is service to customer, write about how to improve that. When you write about stuff inside a company, you will find an audience, because people in a company need information, and if you are generating it, you are valuable.

In the larger marketplace, you can become more valuable by learning the tools and techniques and best practices that are used by most technical writers. In its day, Interleaf was great for book authoring and publishing. But times have changed and we must help with other aspects of content development, delivery, and maintenance. So what are the tools most often used in our industry?

  • online help
  • authoring
  • doc repository
  • content management
  • social media
  • basic business communication tools (frequently MS Office tools)

Are you fluent in the best of those? I do not agree that writing alone is what will keep us employed. Technical writing means knowing the technology about which we are writing and knowing the technology used to develop that content. It is not one or the other. It is both. That is what defines us and what makes us valuable.

Michael’s advice about writing every day is a good start. But don’t stop with that. Try these:

  • help someone find information every day
  • write in as many places and media as possible – not everything belongs in a doc.
    (If there is a wiki or intranet or internal blog, put it there. if a video would work better than a procedural doc, consider making a short video.)
  • find a way to make it easier to find information
  • teach someone how to help information flow
  • learn some aspect of the technology every day
  • learn the new rhetoric – keywords and online page ranking
  • learn how to create filters – pare down content to the essential information and help others do the same

And I know Michael would agree with this piece of advice that applies when talking about how to be valuable and leverage your skill set as a technical writer: Find a mentor. This is a great way to find out if you are well rounded with a good portfolio and a proven skill set. A mentor can help you gauge how marketable your skill set is and where you can improve. Michael Harvey is one such mentor and I challenge him to write more about our profession. He knows I will be there to make sure his communication is concise and complete.

Posted in Criticism, Philosphy, Profession, Resources | Tagged , , , , | 5 Comments

Publishing and Communication

Posted on September 24, 2010 by Bill

My brother emailed me about the upcoming O’Reilly conference (Publishing without Boundaries: What’s on the O’Reilly Radar for the Future of Publishing, presented by: Andrew Savikas, VP of Digital Initiatives, O’Reilly Media.

My response:
You might not know this but I’m inundated with emails about web content and videos and trade shows and web casts and books about the topic of the future of publishing. Sigh. It’s really for the big publishing giants who can’t react quick enough to the change in technology. “Uh oh, now how do we do what we’ve always been doing?” Well, maybe you have to STOP doing what you’ve always been doing!!
For my work, the companies I work for can change quicker and decide to not publish books anymore – now we do PDF files (1990s), now we do online help (2000s), now we do collaborative user-generated docs in our social network (2010s). So we don’t need to know the “future of publishing” because WE ARE ALREADY THERE!
Of course, it’s not that simple necessarily; we all know how hard it was to get management to move away from books to online, and away from PDFs to online help, and now to social media. But it can happen quicker in smaller firms, and it often happens by necessity – the business needs often can drive the change to the newer (cheaper!?) media.

So my brother said:

I like your summary and time line. Now for the 2020′s, what’s next?
I’d guess/use video – it’s so easy to make on a mac that I can see that’s where (some) user docs could/should go next. It’s boring or even unintelligible to read about switches in a car – but to really *see* where the button is located and watch someone activate it makes a better user guide.
Of course video access is horrible as reference guide – tough to search, tough for random access. Still, I see things moving that direction for some “docs”.

And my response:
Of course.
Technical communicators know this. We’re dumb users too. We use YouTube, we search for info using Google. We know this is how today’s users are. Each of us has to convince our management that this is the direction we should go with our content. Whenever I see a product that could use a video or a doc that should have a video in it or with it, I don’t blame the technical writer, I blame the management who don’t unleash the creative potential of the workers.

1. Boundaries and Containers
We are stuck with the legacy of thinking of docs as containers. Videos are great for tutorials and online learning. There are a range of things and, with the web, the old boundaries blur – Is a video a tutorial or entertainment or marketing or all three? Is Google Docs a collaborative document or a white board? Is Pandora a radio station or a web site? And don’t get me started about content not being just for humans but also machine readable or at least web taggable! Documents are the horse carriage of the information age – it’s not just that the information about the product became more valuable than the product (which was revolutionary enough) but it is also the access to the information which is now instantaneous and available worldwide. That’s what’s revolutionary about it – by making it digital and posting in on the Web, it’s available everyone instantly. Publishing doesn’t exist anymore as a separate step with its own duration with its specified audience. You don’t publish something to the web. You web. That’s it. You interact immediately with your audience. Why even have a document or a video, when you can Skype with your customer or your vendor? 24x7x365xinfinity.

2. Reference
While videos are great for how-to, we always need a reference to be able to look stuff up.
But my encyclopedic reference manual isn’t a doc anymore. When you have a question, you don’t look up my reference manual. You go to a search engine and type in the error number or the sprocket number and other keywords. My reference manual is now online so it doesn’t need to be thought of as a separate book. The information is on the web and searchable, so you can find it. That’s all you need to know. How I publish it doesn’t matter as much; how I tag it with keywords is very important now.

This is the big step that technical communicators have to make – not just making and editing content but helping companies engage with customers online.

Posted in Future, Practices, Profession | Tagged , , , , , | 1 Comment

Business Analyst Basics

Posted on September 15, 2010 by Bill

Part of our role as technical communicators overlaps with the role of the business analyst. I know this first hand; I have been asked if I’m a business analyst at work. Inserting myself between development and the customer is just one of my skills. Business analysts establish requirements, improve processes, and add business value by lending their expertise.  The International Institute of Business Analysis is an independent non-profit professional association for business analysts. There’s always the Wikipedia page for Business Analyst that serves as a simple introduction.  Then there are sites that portray the business analyst as an essential interface between the customer and the development team. For those of us technical writers who have advocated for the customer, this work sounds familiar. For more see the articles on businessanalyst.com. While many people come into our profession from other walks of life, it’s also true that technical writers go on to become successful developers, managers, and business analysts. There’s a good article on the transition from Technical Writer to Business Analyst.

For a good list of business analyst competencies, see How to Become a Successful Business Analyst. Of course, where the business analyst can fit in to an Agile process is as an agile analyst or product owner. Closely related to my current work as an information architect is the whole notion of representing those crucial elements of communication. For more information on information architecture, see the Information Architecture Institute.

For jobs as a business analyst, type in “business analyst” and your location in Indeed.com. That’s a start. I’ll blog more about my work as technical writer and business analyst more in future posts. And I’ll blog on information architecture too. More to come.

Posted in Profession, Roles | Tagged , , , , , , , , | Comments Off

LinkedIn and Locked Down

Posted on September 13, 2010 by Bill

I have found it helpful in my own professional networking to use LinkedIn and over the last few years I have developed my page on LinkedIn almost as my online resume. It is certainly the social media equivalent of a resume, with references right there and links to my online slide presentations and more. And I would recommend to any professional, certainly to anyone in technical communication, to get a LinkedIn account. One of the cool features I have discovered only recently is the ability to move areas of content around on a page. For example, I have displayed my experience above my education, but someone more academically based could put education at the top of the page. I’m not sure I can do the same with the second column (where my recent activity and my references to others are displayed) so I still have a lot to learn about LinkedIn.

Lately LinkedIn has been adding some strange stuff, which I am guessing they want us to see as features, but have just left me scratching my head. Check out this latest display of numbers that appears on my internal page:

LinkedIn Stats

I’m not sure why they are showing those numbers in such large and bold font. Anyway, if anyone has ideas about the value of that feature, let me know. It looks like motivation to click on the Add Connections button.

Also, on LinkedIn, I’m intrigued how people are using the groups. CMPros is exhibiting behaviour similar to what I see STC doing, and I’m a little concerned about it. They are announcing a group on LinkedIn, which sounds great. But the group is open to CMPros members only, so if you are not a member, you are out of luck. Here’s the announcement:

CMPros Announcement
It’s billed as helping the community — notice my underlines in the first paragraph, but it’s limited to members only. The technical group working on the Content Management Interoperability Services (CMIS) standard is open for all and there must be an online forum which should be available to everyone. So why would someone go to CMPro’s LinkedIn group for interaction when they can interact directly with the CMIS technical group. This seems to defeat the whole purpose of using the Internet and social networking. Or am I missing something? If CMPros is offering a forum for everyone, that’s great, but that’s not what this group is offering. I would appreciate someone explaining this one to me. Here is the link (if you have a LinkedIn account):

http://www.linkedin.com/groupItem?view=&gid=2716&type=member&item=29139414&goback=.gmp_2716

Posted in LinkedIn, Profession, Social Networking | Tagged , , , | 1 Comment

Beyond Paper Platform

Posted on September 10, 2010 by Bill

As technical communicators, much of our effort is spent working with documents, which is the way information flows in many institutions, and often those documents are on paper. Much has been written about the paperless office as a goal that was never achieved. But the goal of the paperless office was not to get rid of paper per se, as if project managers had an agenda against the lumber industry. There will be paper documents in use in the enterprise for many more generations. The goal was to overcome the limitations of paper in the enterprise for the majority of communication. Now that we can communicate instantly and simultaneously with several people who may be geographically and even departmentally widely separated, we are discovering that paper, and even the document as a separate thing may be a thing of the past simply because it is too restrictive for the needs of communication. It is really the office-less office that was the goal, not the paperless office.

After the car was invented, it was called the horse-less carriage. It was difficult for people to change their image of transportation. The car is more than just a carriage without a horse. It can do more than move people. It provides the mechanism to move beyond the agrarian limitations of space. Now you can drive in a matter of days across a continent. And while it performs more efficiently, it also requires an infrastructure of gas stations and roads in order to really work well. In the same way, the network of computers does more than simply replace paper-based communications systems. The networked communication infrastructure does not simply make a paperless office, to use the metaphor of a previous age. It now makes possible the ability to communicate with all parts of an enterprise and destroy time. The goal was to free the decision maker’s need for timely information by replacing paper-published documents that could only exist in certain places at certain times. Now the flow of information to the community in the enterprise, the ultimate goal of communication, can occur instantly and the information can be available at all hours anywhere in the enterprise.

So besides overcoming the limitations of space by making the information available throughout the enterprise, the limitations of time are also overcome. Time to market is as important as product quality and product functionality. The pace of development of a product and the delivery of a solution is accelerating and the time of usage is shrinking as we obsolete our computer systems in shorter and shorter times.

The point of going online was not to move the information to the computer as if computers were a much more impressive medium than paper. It is not a high tech version of print media. Computers are not a new weapon in the paper-scissors-rock game, somewhere between scissors and rock. The goal is to get the information, whether it was documenting the code or summarizing the report of output data, closer to both the source and destination. If the computer program has a user manual, and the frequency of changes to the program increases faster than the updating of the hard copy manual, then one solution is to make the documentation effort more responsive to the changes by putting the documentation along with the code — put the electronic files in the same repository as the code or even embed it as comment lines in the code itself. Whether it is compiled online help that links to the program or comment lines that can be automatically extracted and reformatted for human reading, the goal is to get the information about the algorithm or about its use as close to the algorithm as possible. In other words, it makes maintenance, or what is today touted as management, of the documentation easier and cheaper.

Part of the new paradigm or at least the new platform is a new way of businesses interacting with each other. No longer is a technical communicator working on one product for one company. The classic image of Kurt Vonnegut taking engineering notes written in jargon and gibberish and composing nice paragraphs explaining the usage of a single IBM computer was lost in the ‘60s. Today we write about a product that is then integrated into a larger system and another writer has to combine information. A third company sells the product and has to modify the documentation with their company image on it. And it may also end in user-commented social media. The end user may be several people down a chain of resellers and planners and purchasers. A better description for the technical communicator would be one involved in the infrastructure of knowledge than as a writer of technical literature. And how the user interacts with the information may be very different from a person sitting reading a book.

The paradigm shift is not from hard copy to soft copy; it was away from paper documents that could only be read by humans one at a time to a medium that is always on and that allows machine processing as well as human reading simultaneously and at any time.

Posted in Philosphy, Process | Tagged , | 1 Comment

Comments from the Peanut Gallery

Posted on September 8, 2010 by Bill

Okay, I’ve received several communications about how I didn’t allow comments on my blog. Well, I’m trying to rectify the situation but I’m not sure I can turn on comments for posts I’ve already posted. I hope as of this post that comments will be allowed from now on. Hearing from you is important and I am listening. I thought I had the option selected for allowing comments but apparently I didn’t. Thanks to those who mentioned it to me. I know that comments are important and part of the give-and-take of social media. Comment away.

Posted in Blog | Tagged , , , | Comments Off

Real-World XML

Posted on September 5, 2010 by Bill

If you are looking for real-world technical communication examples of XML, be sure to check out The Rhetorical Nature of XML: Constructing Knowledge in Networked Environments, by J. D. Applen and Rudy McDaniel. The final chapter has several case studies, one of which I contributed from my work at FarPoint Technologies (before they were purchased by GrapeCity). The book’s web site is http://rhetoricalxml.com and the wiki where several of the case studies are readily available are at http://rhetoricalxml.wikispaces.com. I will let you read it and decide whether the authors are correct about their assessment of the rhetorical power of XML tagging.

There are more uses of XML than can be covered in one book, but my cooperation with the authors was an attempt to show that those efforts to use something as universal as XML do not have to be complicated or expensive. I hope that this book, which studies the use of XML at the intersection of technical communication and knowledge management introduces another generation of technical communication professionals to the flexibility and power of XML in the real world. My apologies to the authors for not blogging about their work more earlier; it came out as I was transitioning from one job to another.

Posted in Resources, Tools, XML | Tagged , , , | Comments Off

(Technical) Language and (Technical) Thought

Posted on September 1, 2010 by Bill

I had an interesting email exchange with my brother, Carl, about language and thought. He works for Cray as a programmer and is working on his doctorate. While our discussion did not relate directly to either his employment or school work, there are implications in the work that both of us are doing in the technology arena. We both were looking at a recent article by Guy Deutscher about the Sapir-Whorf hypothesis:

Does Your Language Shape How You Think?

My brother wrote “I was a big fan of the ‘Sapir-Whorf hypothesis’ as we learned it in Psych 101 – but I don’t remember it being as stridently limiting as this author claims, that Whorf said it kept people from learning the other concepts. But maybe that was the softening edge that Sapir added to it. As to his claim of “no empirical evidence”, I found an abundance of it in the microcosm of programming languages and programmers programming.”

Indeed there probably is an abundance of evidence in the programming world – picking a programming language determining how you solve programming problems. I wonder if others have written about this. I’m going to ask my brother to write more about this. Certainly we are all familiar with the aphorism about everything looking like a nail to someone who has a hammer. That could we be true of our help authoring tools, our web content architecture, and more. Does the jargon and language we choose to use in technical communication determine how our readers think? What do you think? (And what language are you thinking that in?)

TweetCloud

Oh, and Rick, I fully expect you to weigh in on this one!

Posted in Criticism, language, Philosphy | Tagged , , , | 1 Comment

Heart of Technical Communication

Posted on August 31, 2010 by Bill

Tools and trends in information technology are changing the way we communicate and, at the same time, the way we communicate is transforming the technological arena in which we work. Technical communicators are at the heart of these trends and these technological transformations. These professionals must determine whether they will be part of the game or give the reigns of thought leadership to another group. There is no single unified profession called technical communication, but many professionals have used that phrase in the decades preceding the opening of the Web to social networks and collaborative spaces to describe their work and their value to the corporate enterprise. The state of communication is changing from one of publishing with defined channels of communication to one of collaboration and ever-changing ways to communicate. The terrain is not always easy to navigate.

Most people do not understand technical communication as anything deeper than technical writing, which they perceive as something English majors do when they graduate and want to get a job in a high tech work force. But those of us who have some experience in the field know that there is a discipline behind it and it is our job to articulate it. Part of the problem is that there are many university professors who are teaching what they call technical writing but which is not what documentation professionals do in industry. Those of us who work in the field have neither the time nor the resources to articulate what we do or to convince anyone that it is an important job. But with changes in industry, there are reasons to take the time to explain it and there are Web tools available that make sharing that information and collaborating about answers much easier.

Laptop People in Room

In the past it was mainly documents and we distinguished ourselves from the broadcast communications media which was controlled by Madison Avenue and broadcast to the widest audience while we created documents spearheaded for specific audiences for specific reasons. Now we publish on the Internet, on the web, for the widest possible audience, yet aimed at a more specific audience for a more limited time as technology becomes obsolete more quickly. Broadcast media is public; technical documentation is corporate. Document types are blurring as we go online and out of time. White papers are advertisements and tutorials at the same time. Reports are reference material and marketing spin at the same time. Online help is technical support and user manual at the same time.

The reasons for, and value of, technical communication are not often visible to lay people, and not always apparent to professionals. It is not solelyabout writing, as in writing a good book. It is also about speeding the flow of information that must be put together in new ways for the health of the enterprise, not for the consumption of a mass-market individual. We differ from the novelist not simply because we do not express feelings and inward thoughts but also because we do not write for the individual reader alone. While some of what we create is the written word to be read by individuals, technical communication must develop content and structure information not only with computers but also for computers, as well as with and for human readers. The differences with traditional disciplines have not been well articulated. This has resulted in two trends that must be reversed.

First, we have allowed sub-disciplines to splinter off; there is knowledge management, there is content strategy, there is information architecture. They are all part of an overarching communication profession, but vie for attention and race for the consultant dollars claiming they are the chosen career, the true center of the profession or their own profession.

Second, there is this strange and persistent association of technical documentation with writing as taught in university English curricula. We need to break the connection with university English departments because they keep monopolizing the discussion about what is the core of our profession. What makes it a discipline is the business, the business value, the use of communication to allow business to operate, to make money, to accomplish its goals. The profession is too encumbered by its historical relationship to academic institutions that are steeped in the old paradigm, instead of to business, which is quicker at evolving. With their origin in academia and their continued association, many in the profession are afraid to step out and grab the baton and continue the race. The direction of technical communication is toward more complex relationships — relationships that are allowed in business but not well understood or encouraged by academia. The sooner we break those bonds, the sooner we can reestablish much needed newer ones that will help bolster our profession.

It is becoming apparent that our profession is heading in the direction of treating content development as a transition to another stage. I encourage managers and project leads to innovate with content development and delivery and automation, with finding new ways of reaching specific audiences without forgetting the technical innovation that is possible. And I also encourage us all to help with articulating what we do and why. Technical communicators are doing great work, but we are only beginning as a profession. What we are transitioning to may become clear as we dig into the discipline of technical communication.  For those of us who have worked for years with documentation and knowledge of this sort are beginning to see that what is called for is a democratization of information, a freeing of the constraints of knowledge in an enterprise that will have as much an impact on the structure and operation of the enterprise as political democracies have had on equally large organizing social structures. More about this in a future post.

Posted in Criticism, Future, Philosphy, Profession | Tagged , , , , , | 1 Comment

Foundational Skills in Engineering

Posted on August 27, 2010 by Bill

Every once in a while I become philosophical about my work and about the schooling I’ve received. This is something I have wanted to write for a long time (and on which I may expand more later). In my study of engineering and my work as an engineer, there was no class on the philosophy of engineering, but if there were, maybe this would be part of it. Whereas English or writing as a discipline has literary criticism to evaluate it and critique it, I don’t know of anything analogous to the engineering discipline. Usually, either a system works or it doesn’t, it lasts or it doesn’t, but one doesn’t talk about rating if something is good engineering or bad engineering in the way that one talks about good literature. But I have to start somewhere, so here it is.

The Discipline of Engineering
The discipline of engineering involves three core skills. These are not taught in a single class or presented in any concise program that I am aware of. But, for those of us who followed a formal education at an engineering school at a university, these are learned through many classes and labs and reading and working with professors and colleagues. They are three common threads woven through the fabric of the engineering school experience and are found in any engineering endeavor. I am talking here in general about the engineering endeavor and not a specific formalized program that results in professional credentials for a subset of talented people. While I learned these skills while studying engineering at a university and then afterwards putting these into practice in the workplace, one does not need to study engineering to have these skills or to have this approach to solving problems. (I know several individuals who possess these skills who have had no formal schooling or training.) These three skills are common across the many types of engineering and they are what ties them all together and allows us to refer to that discipline with a single name — engineering.

Deciding Among Trade-Offs
The first skill may be summarized as “deciding among trade-offs to reach a defined goal” and usually involves, but is not limited to, the constraints of physical reality. This skill assumes that the parameters being considered can be quantified and added to an equation or something that can be calculated. The implementation includes quantifying certain aspects of reality and working within boundaries set by what can be quantified to acheive a goal presumably for the common good. Of course this skill does not entail actually defining that goal or developing the values that define that goal. Rather, the engineer’s talent is with reducing the problem to measurable and quantifiable terms that can then be weighed to lead to decisions about how to achieve the desired result. An example of this skill would be to figure out how to build a bridge across a river to allow human or other traffic to flow. There are materials to consider, laws of physics that define which designs will work to hold up what weight, and even costs to be weighed. But the entire project, from an engineering perspective, involves deciding which contraints to work within.

Translation Between System Representations
The second skill may be summarized as “translating between equivalent abstract representative systems or between equivalent energy systems”. A perfectly realistic example of this is in the use of electrical energy that is generated or translated from the turning of a turbine from falling water, the transporting of that energy along lines to a substation miles away and then transporting it where it can be converted to energy to heat a toaster in my kitchen. The mathematics involved with achieving that infrastructure is not trivial. The translation between different forms of energy, the translation across types of control systems (mechanical, electrical, chemical, etc.), the translation of physical laws to abstract representations and then back again, all these translations are done with no hesitation.

IBM Guys

Realizing Underpinnings
The third skill may be summarized as “realizing the background infrastructure”. This involves the ability to understand and appreciate the workings of systems that are not always visible. Some examples of artificial systems are the engine under the hood of a car, and the collection of electrical wiring and plumbing pipes behind the plaster of a building’s wall. Some examples of human systems are the computers and financial processing behind the tellers in the bank and the research center behind the walls of the hospital. Engineers can uncover the cause of the effect, they can realize the underpinnings of systetms. I give all these examples because there are so many ways in which we construct and engineer systems. We almost forget that underneath the streets and sidewalks are drainpipes and conduits with fiber optics.

These may seem like three abstract skills but they are foundational to what engineers do, how engineers see the world, and why engineers solve problems the way they do. They can reduce physical problems to their bare essentials, they abstract the translatable aspects of systems, and they can appreciate the infrastructure that keeps complex systems working.

Posted in Criticism, Engineering, Philosphy, Profession | Tagged , , | Comments Off

Getting Started in Technical Communication

Posted on August 26, 2010 by Bill

A lot of people think you need a credential to break into the field of technical communication. You don’t need one to get started. This might change in the future with the STC pursuing the offering of a certification. Most job descriptions I’ve seen have various requirements but if you can prove you can write (or communicate) and have some aptitude in the business or technical or medical field, then you are ready. I don’t think it’s very high barrier for entry level work. There are, of course, levels of expertise and specializations in various industries, but by and large, getting into technical writing is as easy as getting into business. Just do it. At least that’s been my approach.

First, you don’t necessarily need more education – what jobs have ever said you need a master’s degree in online help?! Of course, if you see twenty job descriptions that say Tech Writer: Must have FrameMaker skills, then, yes, maybe you should learn FrameMaker (if you don’t already). But you don’t even need to take a course or buy a book these days – just download an evaluation copy and learn it. Now-a-days, you need to know the Web – anything related to working with web content will look good – but you don’t get that from school. You get that from working on real-world projects. If you have business analyst’s skills, you are all set; knowing the business value of communicating is a great asset.

Second, you break into tech writing by, well, by breaking into tech writing. I mean just start doing it. Do you have a job that involves writing or communicating? To some people I advise going to a temp agency in your area and get a job through them. The pay isn’t as good as being on your own, but you get your feet wet and learn the ropes quickly. I mean after working for a while, you learn what companies are hiring and what they are looking for. Then you can go out on your own. Some people feel safer with some hand-holding. Temp agencies are good for that.

Third, and this is advice that goes beyond my initial post about breaking into the field, find your niche. Find a part of technical communication that makes you stand out – for me, I can do software API documentation better than most and I’m familiar with the tools for doing so. By finding some part of the field that you can specialize in – you can ask for above average pay. Don’t aim for entry level jobs – take them if you must, but aim higher. On the flip side, don’t overspecialize: don’t define your work so narrowly that only one company will ever hire you – find something that is marketable. But I’m getting ahead of getting started.

There is no secret to technical writing – it just means using writing (or whatever form of communication makes sense) to communicate ideas in a particular context – usually a business context, and usually of a technical nature. In the old days, when engineers invented new gizmos like automobiles and jet engines, you’d write a user manual or a repair manual and write out in words what to do. Now, with the web there are tons of ways to communicate and you don’t need to even follow the book paradigm to containerize the content. With some business experience, you know the business value of communicating – you talk to the subject matter experts about the material and then you write it down (since they either don’t have time or aren’t good at writing) and then deliver it to the audience that will pay for that information. Technical writing is not a mystery. It’s just that originators of the information don’t want to write and the consumers of the information are screaming for information, so those of us who are good at figuring out what to write (and good at writing) just write it and deliver it to the consumers.

For ideas of where to start – I say apply for that job and stop being bashful. Go to www.indeed.com and type in “technical writing” and your city. Look at the results, find the entry level position or ones you feel comfortable with, and apply. What can you lose? Or pick an open source software project and just start trying to document it. Now there’s a challenge. And then put that in your portfolio and on your resume. That community of developers can be your reference. If you want to volunteer, great, but there are plenty of paying jobs. Just get out there and start doing it. The majority of us came from other fields. I personally applied for a tech writer job after working as an engineer for a while – I applied for a job as Writer/Engineer and got it. (Okay, so I had a head start on the technical part of tech writing, but I started with some pretty crazy communication jobs to begin with.) From there I started my own company doing technical writing – that’s another option for you. Start your own company and respond to places that need a contract tech writer. Line up a bunch of clients and keep the ones you like. I did it for three years before realizing I’m not good at running a business and keeping a family too. So I cashed in my company to a competitor and settled for an ordinary job. I’ve worked in many types of companies. The challenge is all the same – producing and delivering content in a certain context that helps the flow of information from those who generate it to those who need it. There are a lot of ways to do it, and there is no one that knows the perfect way.

For me, books written about technical communication and all these courses in schools, and degree programs as well are a good credential if you need one. In my career I’ve just learned on the job and while on one job, I picked up skills that helped me land the next one. Schools are good at academic things, not at business things. When business schools (that give Masters in Business Administration) offer a tech writing degree in their school, then I’ll get that degree. As long as they are in English departments or Engineering schools of universities, they are not exactly real-world and not equivalent to work experience. I don’t know about Library and Information Science degrees; that’s another type of degree to consider, since so much of the information jobs these days have to do with organizing and cataloging and architecting information. In an upcoming post, I talk about certifications in business analysis and my latest dealings with information architecture.

Posted in Philosphy, Professional Association | Tagged , , | Comments Off