tag:blogger.com,1999:blog-190059492024-03-07T18:13:11.698-08:00semicolonDedicated to the ramblings of a technical writer and media gadfly.Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.comBlogger44125tag:blogger.com,1999:blog-19005949.post-38222998276748162632009-09-22T06:03:00.000-07:002009-09-22T06:05:10.559-07:00bravo to Chrysler'shead of technical publications:<br /><br /><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: 'Times New Roman'; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;"><span class="Apple-style-span" style="color: rgb(51, 51, 51); font-family: Arial,Verdana,sans-serif; font-size: 14px; line-height: 18px; text-align: left;">Chrysler announced that digital owners’ manuals will replace their paper predecessors starting in 2010. The automaker is the first to switch from dead trees to DVDs, and estimates the move will save 930 tons of paper annually. </span></span><br /><br />read on: <a href="http://www.wired.com/autopia/2009/09/chrysler-eliminates-the-paper-owners-manual/">http://www.wired.com/autopia/2009/09/chrysler-eliminates-the-paper-owners-manual/</a>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-48222453472088726682009-07-23T05:22:00.000-07:002009-07-23T06:44:13.747-07:00GUI based application help<span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: 'Times New Roman'; font-size: 16px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;"><span class="Apple-style-span" style="color: rgb(65, 65, 65); font-family: Helvetica; white-space: pre-wrap;">I started responding to <a href="http://www.thecontentwrangler.com/article_comments/do_screen_captures_still_makes_sense/">this article</a> about not include screen shots in GUI documentation. Then I went off topic so I'll just post my thoughts.<br /><br />The problem of managing screen shots in GUI application documentation has dogged me starting 15 years ago - fresh out of college and a new tech writer.<br /><br />Creating and maintaining documentation that includes screen shots is a nightmare. I'm surprised that GUI API suites haven't created a tool to make images and image regions structured. Pairing that with an authoring application that understood such structure and could apply style rules to the interaction of the master document's layout could help.<br /><br />Actually, when you think about it, it's crazy that we document on-screen procedures in a separate paper-document or window. I'm sure those of you who write docs for GUI based applications on a daily basis think about this all the time.<br /><br />An alternative is for help to be delivered as an overlay/layer over the GUI. that would be sweet.<br /><br />Anyway what I'm saying is we don't have the tools for the most helpful Help/documentation. It's a minus for the user and tech writer. And that's sad considering that GUI based applications have been in widespread use for 20 or so years.<br /><br />Maybe someone can point me to a well-woven/efficient application+help example. I'm just not aware of any.<br /></span></span>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com1tag:blogger.com,1999:blog-19005949.post-33295412112013930442009-05-11T05:52:00.000-07:002009-05-11T06:29:52.219-07:00documentation nightmares: car seats<div>I was going to make this post 3 years ago, but didn't. Now I have another opportunity.<br /></div><div><br /></div><div>I consider myself technically adept at mechanical things. </div><div><ul><li>Building Ikea furniture? Easy and fast - rarely do I need the directions.<br /></li><li>Fix my car? Sure, I'm at home under the hood and under the chassis.<br /></li><li>Soldering circuits? Been doing that since 6th grade.<br /></li><li>Fear of disassembling anything? Nope not really.<br /></li></ul></div><div>So you would think that installing a car seat would pose no problem, especially after I've had experience, and considering I am a documentation professional. Well, no.</div><div><br /></div><div>Certainly you want absolutely 0 margin of error for your car seat installation. This is my family's 3rd car seat - the one we purchased this weekend was a Booster / forward-facing-harness seat. And like I always do, I stuck to the directions. And that's where I failed.</div><div><br /></div><div>Here's the problem as I see it: The pocket-sized, 35-page guide includes procedures for:</div><div><ul><li>Booster seat operation<br /></li><li>Harness seat operation<br /></li></ul></div><div>And attaching the seat to the vehicle via:</div><div><ul><li>LATCH<br /></li><li>Seatbelt with shoulder strap<br /></li><li>Seatbelt without shoulder strap<br /></li></ul></div><div>So that's potentially 6 scenarios. In addition, the text warns of procedures <span class="Apple-style-span" style="font-style: italic;">not</span> to follow that may only be applicable to the scenario you are not following. It's confusing, not reassuring, and highly annoying. </div><div><br /></div><div>My guess is they cram all this information into a little booklet to stay attached to the car seat, and the lack of clear directions is probably designed so they can CYA, legally.</div><div><br /></div><div>I don't object to including the product manual as is, but they should publish more refined instructions in a larger format. A nice 2' x 3' poster with line graphics that tells you each step you must explicitly follow would be a great start. In fact, one poster-sized document per scenario would be very good. Personally I think the best solution would be for their documentation to interface with a database of car specifications. You could go to the website, choose the car seat model, choose your car model, and their system would automatically generate the documentation you need.</div><br /><div>(Image courtesy of <a href="http://www.flickr.com/photos/geodanny/">dfb)</a></div><br /><img src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj_Ttkhy8Z6VQwALvTC5zgeiJCgcwDENmj_uWpgukJoJrMWPVLXKAVxPNHKATK7BMsP0XsKojcFIEweNUHhPL98DXTZeQd3IXapCxkXQJ8vyOm1Lv4CKbWBP2FbLAEDNLp9iVz6rw/s320/2519546452_9dc61fa1f8.jpg" />Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-42019129936858752832008-12-15T08:56:00.001-08:002008-12-15T09:04:57.224-08:00tech writer job securityI think these days every worker is looking over his or her shoulders for the proverbial pink slip**. While companies are probably going into hibernation mode, let's remember how important documentation is.<div><br /></div><div>A complete product includes documentation. It might be a formality that people like to laugh at, but it is a requirement. Wise management, under economic duress, will cut development in step with documentation (and sales, and marketing, and support). Very few organizations will purchase a complex software product without a sufficient doc set.</div><div><br /></div><div>Wiser management will realize that excellent documentation can offset a support staff. </div><div><br /></div><div>I've heard the stories about how the technical publications departments are the first to go, but I have a feeling they're exaggerated. And if all the writers are sent home first, as a barometer of the company's health, the whole development staff is not much behind.</div><div><br /></div><div><br /></div><div><br /></div><div>** note: a simple way to stay somewhat sane is to NOT read economic blogs. they will scare the heck out of you.. ask me how I know :(</div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-87477554611074873652008-12-09T09:01:00.000-08:002008-12-09T09:35:25.834-08:00detailed conceptsThe following thoughts were initiated by <a href="http://4jsgroup.blogspot.com/2008/12/move-over-dita-chaos-is-coming.html">reading this great post by</a> <span class="Apple-style-span" style=" white-space: pre; "><span class="Apple-style-span" style="font-size:small;">Alan J. Porter</span></span><span class="Apple-style-span" style="font-size:small;"> </span>on how traditional structured content is losing primacy.<div><br /></div><div>Structured and formal content is not going anywhere. It is probably still as important to our ways of exchanging, archiving, and mutating ideas as ever. The rise of the web, of so much of the whole of human experience available to us at any moment has initiated a period of people using more content than ever before. But it's that smaller pieces of content are being used in exponentially greater amounts. </div><div><br /></div><div>I'll give a quick example that shows where this is happening. Let's say there's some new drug on the market used to treat farsightedness. pre-web there would be research building on theory, and then clinical trials, followed by approval, marketing, and use by the general public (ok this is totally out of my league, but I'm just throwing out an example).</div><div><br /></div><div>Now, the process and documentation of bringing that drug to market were extensive as everything is required to be captured by law. Later, an interested individual would learn about the drug either through their doctor or a friend or advertising. If they had questions, they could ask those people, or maybe find information in some reference guide. Tho' it's unlikely that they could find truly detailed content unless they took up the search full time (or knew how to navigate pharmaceutical/medical references).</div><div><br /></div><div>Today, all of the references are easily available to us. Personal stories about drug therapies are available to us. One can start reading and reading, and if necessary cross reference relevant technical literature, ignoring the bulk of the published literature. Without wading through the mountains of data you could search and find information on <span class="Apple-style-span" style="font-style: italic;">drug X</span> and <span class="Apple-style-span" style="font-style: italic;">high blood pressure</span>. </div><div><br /></div><div>Certainly in the pre-web days this information was available, but it might be pretty difficult to find. The web has enabled more people to access this information directly, leapfrogging all of the background or supporting words that only an expert would have consumed.</div><div><br /></div><div>I believe that we must be cognizant that some of our readers are just looking for small nuggets of information; tho' this audience may only find what they're looking for with a search engine, and they would never use an index. </div><div><br /></div><div>Maybe a good question for the experts to consider is how DITA and other structured formats can optimize their content for search engine crawling and successful hits on a given query.</div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-40008685229037651202008-12-08T09:06:00.000-08:002008-12-08T09:26:39.294-08:00my failure as a bloggerI've been around the block on the Internet. I got my first Internet email account the 2nd or 3rd week of college in '91. To me, the WWW is just one part of the Internet. But obviously things change and mature and I haven't kept up. Which is to say I used to be thoroughly engaged in the culture and society of the Internet, but as we're in post-Web2.0 times, I have lonely facebook, myspace and livejournal pages. My 4 or 5 blogger accounts are mostly stagnant, and my personal website is used as a photo album to share with my family who lives out of state.<div><br /></div><div>I love the technology, but for several years the web has been about people and interpersonal communication more than anything, and I haven't really kept up in this realm. </div><div><br /></div><div>So the other night Arianna Huffington was on john stewart, pushing her book on blogging. Within 6 minutes time she shed light on why it's so tough for me to gain any traction blogging. </div><div>First she says "blog your passions." Ok that's not too tough. <del>I love to write about</del> I have thoughts and opinions I'd like to share about tech writing, and tech, and media, and music (and their intersections). But then she said how blogging is about getting your thoughts down and firing them off quickly...</div><div><br /></div><div>Do you know how many <span class="Apple-style-span" style="font-style: italic;">draft</span> blog posts I have saved???? I think the TW in me wants to take the time to write down concise thoughts, not leave ideas hanging, and try to direct the reader toward a conclusion (don't you just hate it when you post about X, and the thread goes to some minor point you made in passing that could have just as well been left alone???)</div><div><br /></div><div>My wife turned to me and said "you even write out your phone calls before you make them!!" (which i do sometimes because I want a precise query).</div><div><br /></div><div>Perhaps this is where my shortcomings of being a real writer is apparent: Given a controlled topic to write on, I'm good and fast. But given the task of writing open-ended, engaging prose that people want to read and respond to, I fall short.</div><div><br /></div><div><br /></div><style type="text/css">.cc_box a:hover .cc_home{background:url('http://www.comedycentral.com/comedycentral/video/assets/syndicated-logo-over.png') !important;}.cc_links a{color:#b9b9b9;text-decoration:none;}.cc_show a{color:#707070;text-decoration:none;}.cc_title a{color:#868686;text-decoration:none;}.cc_links a:hover{color:#67bee2;text-decoration:underline;}</style><div class="cc_box" style="position:relative"><a href="http://www.comedycentral.com/" target="_blank" style="display:inline; float:left; width:60px; height:31px;"><div class="cc_home" style="float:left; border:solid 1px #cfcfcf; border-width:1px 0px 0px 1px; width:60px; height:31px; background:url("http://www.comedycentral.com/comedycentral/video/assets/syndicated-logo-out.png");"></div></a><div style="font:bold 10px Arial,Helvetica,Verdana,sans-serif; float:left; width:299px; height:31px; border:solid 1px #cfcfcf; border-width:1px 1px 0px 0px; overflow:hidden; color:#707070;"><div class="cc_show" style="position:relative; background-color:#e5e5e5;padding-left:3px; height:14px; padding-top:2px; overflow:hidden;"><a href="http://www.thedailyshow.com/" target="_blank">The Daily Show With Jon Stewart</a><span style="position:absolute; top:2px; right:3px;">M - Th 11p / 10c</span></div><div class="cc_title" style="font-size:11px; color:#868686; background-color:#f5f5f5; padding:3px; padding-top:1px; line-height:14px; height:21px; overflow:hidden;"><a href="http://www.thedailyshow.com/video/index.jhtml?videoId=212824&title=arianna-huffington" target="_blank">Arianna Huffington</a></div></div><embed style="float:left; clear:left;" src="http://media.mtvnservices.com/mgid:cms:item:comedycentral.com:212824" width="360" height="301" type="application/x-shockwave-flash" wmode="window" allowfullscreen="true" allowscriptaccess="always" allownetworking="all" flashvars="autoPlay=false" bgcolor="#000000"></embed><div class="cc_links" style="float:left; clear:left; width:358px; border:solid 1px #cfcfcf; border-top:0px; font:10px Arial,Helvetica,Verdana,sans-serif; color:#b9b9b9; background-color:#f5f5f5;"><div style="width:177px; float:left; padding-left:3px;"><a target="_blank" href="http://www.thedailyshow.com/video/index.jhtml?videoId=166515&title=Barack-Obama-Pt.-1">Barack Obama Interview</a><br /><a target="_blank" href="http://www.thedailyshow.com/video/index.jhtml?videoId=167938&title=John-McCain-Pt.-1">John McCain Interview</a></div><div style="width:177px; float:left;"><a target="_blank" href="http://www.thedailyshow.com/video/index.jhtml?searchterm=Sarah+Palin&searchtype=site&x=0&y=0">Sarah Palin Video</a><br /><a target="_blank" href="http://www.thedailyshow.com/video/index.jhtml?searchterm=indecision+2008&searchtype=site&x=0&y=0">Funny Election Video</a></div><div style="clear:both"></div></div><div style="clear:both"></div></div><div><br /></div><div><br /></div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-567230391513595572008-11-04T07:03:00.000-08:002008-11-04T08:28:02.007-08:00why the attention?So why am I ranting about subject-oriented technical writing? Well for reasons of fate, it's the primary type of writing I've done in my professional life. I'm proud of my work, and I'm proud of what good S-O TWing can accomplish. Yet, I feel like it gets shafted in technical writing communities. (<span class="Apple-style-span" style="font-style: italic;">hey, my baby is beautiful too!</span>)<div><br /></div><div>Take a glance at the excellent <a href="http://writerriver.com/">Writer River</a>. If you read past the headlines, you'll notice that many of the submissions focus on user-oriented writing. I used to read <a href="http://www.techwr-l.com/techwhirl/index.php3">techwr-l</a> regularly, and besides their discussions on the inanities of grammar, and implementing single sourcing through structured languages, the most talked about topic was creating effective documentation through user-centric writing and what it means to be user-centric. </div><div><br /></div><div>Another reason why S-O TWing gets the shaft is the more the writing is only responsible to the facts, the more it's feared by the average professional writer. I say this not from first hand experience, but I'm drawing from years of reading technical writers' ramblings. The essence is that most TWers like to engage in the act of writing (which might have been what brought them to TWing in the first place). Yet S-O TWing zaps much of the enjoyable art and craft from the exercise.</div><div><br /></div><div>There's also no ongoing writing challenge in S-O writing after you get it: once you master the logic of presenting clear, factual, expository or descriptive writing, you've got the craft. What can only sustain you this point is enthusiasm for the content itself.<br /></div><div><br /></div><div>Like everything, this is not black or white. While I can say that my work is mostly S-O writing, if I said that there are no user considerations, I'd be lying. In real life, my work severely tilts heavily toward being responsible to the content, but I'm still mindful that the reader is trying to get a job done. I'm still going to use transition words to make the reading flow, I'm still going to use visual formatting cues to make the document easy for the eyes to follow, and I still mix up sentence patterns so that I don't present 1000 pages of S-V-O constructions.</div><div><br /></div><div>One final note: While S-O writing product usually falls into the class of a project's requirement, it's a business formality. It communicates concepts and details for the sake of reliability and sustainability. Using S-O writing for user-centric purposes gets all sticky, but that's the subject of another post.</div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com1tag:blogger.com,1999:blog-19005949.post-77394481668389667122008-11-04T05:29:00.000-08:002008-11-04T08:26:42.512-08:00subject oriented technical writingIt's been bugging to write down some of my thoughts on a fundamental technical writing dichotomy. Before we can even talk about audience, realize that your documents fall into the following camps (or a combination thereof):<div><ul><li>user-oriented<br /></li><li>subject-oriented<br /></li></ul></div><div>This is important to consider and be cognizant of because subject oriented TWing gets comparatively little attention, yet I believe encompasses a huge amount of professional technical writing output. So I'll give my quick, ideologically-pure definition of subject-oriented writing.</div><div><blockquote>Subject oriented technical writing is only responsive to the topic it documents. It must faithfully and completely explain itself and create new context and explanation where needed. It is legalese in form and does not owe anything to its creator or reader.</blockquote></div><div>So, any time you are hired to document an organization's system, process, or configuration, you are primarily hired to create this type of content. Usually, subject oriented technical writing is a contract requirement meant to capture how the contract was executed. And what's the final destination of this product? Well it ends up on the shelf in a binder, in an archive directory, or on a CD or backup tape stored in a mountainside. No glory for the writer.<br /></div><div><br /></div><div>Let it be said that subject oriented technical writing is dry by nature; it is not sexy; it is just the facts & perhaps even-handedly considered opinions. As a computer industry writer, let me say that the shining example of this type of writing is the <a href="http://www.faqs.org/faqs/">collection of RFCs</a>. </div><div> </div><div>I would guess that something like a tenth of all technical writing is purely subject oriented. </div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-55349030216781546652008-10-29T06:03:00.000-07:002008-10-29T06:23:22.345-07:00Common blog posts by tech writersI find it interesting that so many articles about technical writing are of the <span class="Apple-style-span" style="font-style: italic;">what it's like to be a tech writer</span> variety. Let's posit why this is the case:<div><ul><li>technical writers are vain, and like to write about themselves<br /></li><li>no one ever really set out to be a technical writer, and the journey to get there is a large part of the process<br /></li><li>no one knows what the heck a technical writer is, so we're filling the demand for an answer<br /></li><li>as communicators, technical writers are compelled to share their take on the story<br /></li><li>because tech writers are often playing catch-up with their subject matter, writing about what they already definitively know is an attractive proposition</li></ul><div>I'd give the most weight to bullet point #2. I think there are numerous jobs like tech writing that are hidden within the layers of business, it's just that we have the immediate tools (and free time) to tell the story. The variety of well-paid, intellectually-challenging, nichey jobs in the professional world never ceases to amaze me.</div></div><div><br /></div><div>That said, I'm planning a my post on this topic soon...</div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-20828122801248660062008-09-17T06:04:00.000-07:002008-09-17T06:48:52.313-07:00best practices for moving content between documentsI'm actually here to solicit information about moving content between documents in an established documentation set. <div><br /></div><div>I think the story is pretty common: you've been documenting a product for a number of years - feature XYZ initially had 20 pages of documentation. This grew to 50, then to 100, then added other supporting documents like reference tables. It's time to give this feature its own document.</div><div><br /></div><div>So how do you handle it? Are there any pitfalls involved with simply moving the feature and describing the move in document release notes? Should you put a pointer where the text used to be: "XYZ has been moved to Document #09828202, section 2."</div><div><br /></div><div>Honestly, I don't get much user feedback, except when something is explicitly wrong or incomplete. So as much as I can anticipate confusion, I probably won't get any desperate help requests, but I'd like to do this the right way. How do you handle this situation?</div><div><br /></div><div><br /></div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-25306679436699826782008-08-14T05:26:00.000-07:002008-08-14T06:02:15.381-07:00Tools and User InterfacesNudged by <a href="http://www.idratherbewriting.com/2008/08/13/with-all-this-fuss-about-tools-three-best-practice-attitudes/http://">Tom's post</a>, I have a quick comment on UI awareness.<br /><br />I find it funny that some software tech writers don't care much about user interfaces and application usability. We should have a keen eye for appreciating and advocating the user's needs. It's not a stretch then to apply these considerations to ourselves!<br /><br />My cues that people are not paying attention to how they interact with applications can be demonstrated by their browser use. We get to watch others use browsers in all sorts of informal situations. Here are a few behaviors I've noticed that indicate when someone is not attuned to workflow and UI efficiencies; when the question "how can I do this faster or better?" is never asked.<br /><ul><li>Using the Bookmarks drop-down menu exclusively - It is tough to imagine that some people haven't noticed the bookmark bar.<br /></li><li>One window per webpage - Tabbed browsing was one of the best innovations ever. There have been lots of nice incremental changes, but high praise for this. I still see some users with 12 unique instances of browser windows scattered on their desktop.<br /></li><li>Typing "google.com" manually for all searches. It blows my mind to think that some people haven't noticed the search box next to the address box. Excepting that, you would think that users could at least bookmark pages that the visit regularly.<br /></li><li>Use of internet explorer - I don't care, and I am not a firefox advocate, but anyone who used IE6 through its darkest days is completely out of touch. <br /></li></ul><br />I honestly don't want to sound petty. I believe that GUI-based applications have evolved to a semi-mature level where certain techniques have proven their high worth. When heavy computers users (even if use is only mandated by your job) who should also be attuned to how people use computers don't take advantage of these shortcuts, it shows a lack of a primary skill required for your job (either that or an extreme ability to compartmentalize skills and tasks).<br /><br />It's like there's a "how can I do it better?" circuit that some people don't have or choose not to develop. If I were hiring, the presence of this facility would be a big hire/no-hire determiner.Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com1tag:blogger.com,1999:blog-19005949.post-18679477597705128202008-06-26T06:17:00.000-07:002008-06-26T06:49:38.101-07:00Firefox 3 adoption rate and the culture of the InternetArs Technica (Which is increasingly showing its bias and has lost some esteem as of late) runs this article entitled <a href="http://arstechnica.com/news.ars/post/20080626-20-million-firefox-3-downloads-in-a-week-4-market-share.html">20 million Firefox 3 downloads in a week, ~4% market share</a>. I want to go out on a limb and pontificate on this data.<br /><br />I believe that not everyone who intends to upgrade soon has had the chance. (I upgraded at home on the second day because FF2 was slow and had that memory problem (and my wife would never restart firefox, resulting in frustration for her). I haven't upgraded my 2nd home machine, nor have I upgraded my work machine.<br /><br />But lots of people are enthusiastic for FF3, whether for technological reasons, or for general nebulous Internet enthusiasm (the big news of the week). I'll take a step backwards and suggest that those who upgraded make up most of the Cyberculture drivers (i.e., those for whom the Internet plays a part in their lives). So what I'm really getting at is that Internet-people only make up 5-10% of the Internet. <br /><br />I've noticed in many blogs and articles, tech-writing and otherwise, people make assumptions about users based on what they believe an <span style="font-style:italic;">Internet User</span> is*. But remember, an Internet User is only one who is visible on the Internet, and I believe that only accounts for at most 1 in 10 users. So, my point is for writers/UI designers/etc to be careful to not assume a user's behavior or needs based on 10% or less of the population. <br /><br />*that is to say: <span style="font-style:italic;">I have 254 entries in my blog roll, I wake up to 1000+ new articles in my RSS reader daily, my pajamas have a special pocket for my iPhone so I can read twitter messages in my sleep; this makes up half of my human interaction and now I know what people and computer users are like</span><br /><br />** I am posting this from Safari on windows. I like safari, although its font rendering on XP leaves something to be desired.Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-61903180676668075832008-05-23T04:47:00.000-07:002008-05-23T05:41:48.011-07:00the visual societyDo you remember way back when, in grade school, as an excuse for poor performance, students would say "well I'm a visual learner." And then I suppose sometime in the 80s or 90s it became accepted that some people have an easier time understanding concepts if they don't have to pull the meaning out of pure text. I always felt that with the rise of the GUI, we as a society became more and more visually oriented.<div><br /></div><div>Anyway, <a href="http://graphjam.com/">this website, graphjam,</a> is cute because it indicates how easily we're able to encode pop culture in visual forms. You could probably also say that visual data presentation is so ingrained in our culture that we've reached the point of parody. Interesting to note, often you'll run across a graph where the author either didn't pick up on the subtleties of the saying or lyric, or doesn't quite have a perfect understanding of the visualization technique.</div><div><br /></div><br /><a href="http://graphjam.com/2008/04/21/funny-graphs-gift-sales-1213-1214/"><img class="alignnone size-full wp-image-560" src="http://graphjam.wordpress.com/files/2008/04/funny-graphs-gift-sales.gif" alt="funny graphs" /></a><br />more <a href="http://graphjam.com">graph humor and song chart memes</a>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-89512289956679458602008-05-21T11:36:00.000-07:002008-05-21T11:42:00.689-07:00cool techOK, here's a simple question:<div><br /></div><div>What is (one or two of) the coolest, most interesting, got-your-blood-pumping, technology or concept you have ever documented?</div><div><br /></div><div>Two of mine (working on the big bad production network, no not BBN): </div><div><ol><li>Multicast<br /></li><li>Network performance vis a vis jitter, latency, and packet loss.<br /></li></ol></div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-81678901930088318802008-05-20T05:22:00.000-07:002008-05-20T06:01:21.440-07:00wiki this and thatI'd say that the days I don't visit wikipedia are rare and definitely the outliers. Have you contributed to wikipedia? (I have in 2 minor ways)<br /><br />My post and question on the role of wikis in Technical Documentation is short. Let me first contrast between wikis and formal documentation:<br /><ul><li>Wiki-Generally non-hierarchical collection of documents that can be edited by the wiki's audience.</li><li>Formal Documentation-Rigidly organized collection of documents that can not overtly be edited by the audience.</li></ul>Without laying out some pseudo formal frame work to elicit responses, here is my question:<br /><br />The tech writer generally wears 3 hats: Content Manager, Editor, Technical Writer. Are all three of these hatted people cheering for wikis to supersede formal documentation? If not, what is the balance that should be maintained<br /><br />I ask this as someone who generally acts as a Tech Writer and sometimes Editor, and in general doesn't really like the idea of wikis invading the realm of formal documentation.<br /><br /><br /><br /><span style="font-size:85%;">*Maybe this three-hatted person is known as a Content Professional, but <span style="font-style: italic;">UGH </span>on that title*</span>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-56429492490476874792008-04-18T08:10:00.000-07:002008-04-18T08:14:24.564-07:00Documentation and Change<p class="MsoNormal">Here's an issue that many of us run into (I'd like to think). What happens when you want to change something in your documentation that's not necessarily broken? What’s the best way to handle mere upgrades and nonessential documentation improvements?<o:p></o:p></p> <p class="MsoNormal">I ask this b/c many writers and editors are loath to make changes if something isn't necessarily broken. If a fact is misrepresented or wrong, it's generally not a problem to fix it. But if our evolving experiences can identify a product improvement, it's often a tough sell to make the change.<o:p> </o:p></p> <p class="MsoNormal">Things like boilerplate text, layout, formatting, descriptions, and logical flow of a document are all fair game for improvement. I don't claim to get things right the first time. I don't think it's reasonable to expect everyone to get things right initially. It's only after a waiting period and a sufficient amount of reflection that someone can claim to have nailed down the BEST way of doing something; progress is iterative. I believe that journeymen technical writers have a much higher hit rate of near perfection the first time, and I'm approaching that point - but not yet.<o:p></o:p></p> <p class="MsoNormal">The resistance to make changes I believe comes from the fear that you will confuse and disorient the user. This is a fair critique. A second resistance to change is the extra work that comes along with implementing the change - and the need to implement the change everywhere and at once. A lot of work is involved with a proper system-wide change. Third, a change that works somewhere might break something in a remote part of the system. You're really taking a risk by making changes in a system that already is functional. Fourth, you set a bad example and expectation that nothing is set in stone, and anything can be changed at any moment which might lose your reader's trust. <o:p></o:p></p> <p class="MsoNormal"><o:p></o:p>Please reply and add your thoughts on why non-necessary change should be avoided in technical documentation.<o:p></o:p></p><p class="MsoNormal"><o:p></o:p>I'm planning a follow-up to refute this in a later post, so save your <i style="">change is good!</i> replies for then.</p>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-72432777849140526972008-04-07T07:45:00.000-07:002008-04-07T07:54:58.930-07:00steel cage job title championship matchTwo disclaimers:<br /><ol><li>I acknowledge that these titles are arbitrary.</li><li>The distinction I describe is my own and my thoughts probably represent the minority. </li></ol>Less so in recent years because I've had steady, happy employment, but I often agonize over the definitions of technical writer vis-à-vis applying to job postings. Documentation Specialist is probably the second most common job title (which I held in two government positions) which every TW-type job applicant searches. So when one is bored, fretting, and unemployed, trying to sort out the difference between the two is happily time-consuming. I'll add that the HR people who submit job postings probably don't give the difference a second though. But you know, we're writers - so we obsess over definitions.<br /><br />I don't know if this was the purpose of the blog entry or not, but <a href="http://collinturner.com/pile/?p=35">Collin Turner's discussion of a subject matter expert</a> (SME) has helped me make a sharp distinction between technical writer and documentation specialist.<br /><br />SME is a term that's thrown around loosely (at least in my experience), but Turner starts with a salient point in that an SME "provides needed content." The SME is the source of the content. The documentation specialist then chaperones the content through the documentation process until a product is published.<br /><br />In my limited world view, I'll suggest the following difference: While neither the technical writer nor documentation specialist creates the product (computer application, piece of hardware, or process) that must be documented, the technical writer creates and is ultimate responsibility for the content supporting the product. He or she performs the requisite research inside and outside of an organization to identify, collect, and organize this content.<br /><br />Collin Turner's description acknowledges these internal conflicts, but lays the organizational knowledge arbitration at the SME's feet.<br /><br />When I am wearing my technical writer hat (which I like to wear most of the time), I am navigating my organization and available resources to identify and collect all the required content. This means obtaining different functional organizations' ideas of a product, resolving their differences, and presenting a unified view.** Secondarily, I need to have confidence that I can identify with the target audience in order to create effective documentation from the raw data which I've gleaned. This is a real world description, not some idealistic <span style="font-style: italic;">cut and paste from engineering and marketing documents, fix the grammar and save as perfect documentation</span> dream.<br /><br />I generally feel that a good technical writer must become competent enough in the subject he or she is writing about to answer most questions about it. In the SME-documentation specialist system, the DS has a place to ask questions, but isn't ultimately responsible for the content.<br /><br />The biggest problem that I see is when an SME doesn't have a vested interest in the user and doesn't take the time to understand the user's documentation and learning needs. When the SME is an engineer or scientist, he or she is too busy creating the widget. But this system succeeds when the SME is in marketing and understands that his or her success or failure depends on the customer's success or failure.<br /><span style="font-size:85%;"><br />**Any good TW knows that his or her understanding of cross-departmental viewpoints somehow is really valuable to the organization. If anyone in upper management realized this too, I think that TW's organizational roles could be elevated.</span>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com1tag:blogger.com,1999:blog-19005949.post-14995789763858450662008-04-02T06:19:00.000-07:002008-04-02T06:37:50.081-07:00If I knew then what I know now...This is 1/10th a test if trackbacks work, but mostly a comment...<br /><br />Tom asks the age old question, would you keep doing what you're doing, or do something else. Well I sort of intended to be a tech writer from college...<br /><br />So the funny thing is I don't specifically <span style="font-style:italic;">enjoy </span>writing, but I'm good at it. I realized this in college as an engineering major. Because in those days, putting in hours of required studying wasn't my strong suit, but my passion for techie stuff was, I put these two things (engineering + writing) together and got a writing oriented degree, with the intent of using it in the technology field.<br /><br />Do most people go into their college studies all idealistic and truly want their career to orient itself around their decided major? I don't know - but I did. Would I like to be a full time engineer now? Heh, I don't know about full time, but it's fun to put down your pencil and pick up a development environment application. <br /><br />I've flirted with the idea of other vocations: law (but I don't want to deal with lawyers), teaching (but I like working alone), ISD (same as teaching). These are all in the create or communicate sphere, so I don't know if I'm going so far out on a limb as an oceanographer. OH yeah - I'd like to be a green contractor, but that community is so old-boy network around here, the thought of it turns me off. <br /><br />Would I mind being a TW in 20 years, writing manuals? Maybe not! It's hard to say, but as long as the technology I write about is engaging, there's a good possibility I will be.Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com1tag:blogger.com,1999:blog-19005949.post-25223001271236243012008-04-01T07:17:00.000-07:002008-04-01T08:14:44.668-07:00extra wideWhat kind of display do you have at work and at home? I find these ergonomics fascinating, since your monitor is akin on the wheels on your car or your stereo's speakers; it's the main interface between the machine and what the machine works against.<br /><br />At home I share 1 13" laptop. The screen a little bit small but fine for its intended purpose. I will say that if you're in the market for a laptop that you will use for more than Office-type or web browsing applications, splurge and get it with a screen that has a decent off-axis viewing angle. We watch a lot of DVDs on the laptop, and it's narrow viewing angle is limiting.<br /><br />At home I also have a beautiful 21" trinitron CRT display for my desktops. What more can I say, this is what I was pining over 10 years ago. Accurate, bright colors, with detailed resolution. Plus it doesn't have to deal with the ClearView-type font dithering that most LCDs are sensitive to. The only downside is that it sucks about 120 watts of power and is HUGE.<br /><br />Finally, my work displays. I started with a 19" Viewsonic CRT - Fabulous monitor. Then moved to a 17" LCD, this was a step backwards because of the reduced resolution, and as I recall, going from a curved screen to a flat screen was a little funky on my eyes for the first few days. I also remember that the LCD screen was too bright. This made it a little bit difficult working in a dim environment because the screen was blaring in your face. Next came an upgrade to a 19" LCD. Now we hit the sweet spot! The 19" had a fine amount of resolution (2 documents side by side in Frame), good color accuracy, and showed precise text once I got the hang of Clearview. I was happy.<br /><br />But wait - so then the paradigm shifts when I got a 24" HUUUGE wide screen LCD display at work. At first I was blown away - our home TV is 19", and this screen feels much larger than my 21" CRT. I'm going to make this long story short:<br />For the way I work, a widescreen is overkill. I work very linearly, I don't need to see or refer to 5-10 different pieces of information at once. I generally write a document straight through, edit images one at a time. There are few dynamic dependencies. I'll contrast this with when I was coding or designing websites, where you need to refer to several windows of information at once.<br /><br />The split screen feature in MS word is great for viewing two parts of a document simultaneously, but that's the most I've ever needed. Now I can have 2 frame documents side by side, but at almost 100% for each. This is nice, but unnecessary. Further, there's the potential to have too much visual information, such that it can be distracting.<br /><br />Do any other TWs out there use wide screen or multiple monitor set ups effectively, for the TWing part of their job? I can see for content management or designing a help system, it could be useful, but for the straight task of writing and editing text, I'm completely unconvinced.<br /><br /><br /><a onblur="try {parent.deselectBloggerImageGracefully();} catch(e) {}" href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEivjoG7Rw9PFZ_LNTABeQWSIvHMiTLmwN0q_tSjn4K_x1u2A445OITxc6RiShaFt79bnnX6zVmPHoLyftBPl795h1YBieuvs0MJ7AOzbMHbEFXrhqwZfPGvB67GIGMnj7fYYNLVFQ/s1600-h/lx3.jpg"><img style="cursor:pointer; cursor:hand;" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEivjoG7Rw9PFZ_LNTABeQWSIvHMiTLmwN0q_tSjn4K_x1u2A445OITxc6RiShaFt79bnnX6zVmPHoLyftBPl795h1YBieuvs0MJ7AOzbMHbEFXrhqwZfPGvB67GIGMnj7fYYNLVFQ/s320/lx3.jpg" border="0" alt=""id="BLOGGER_PHOTO_ID_5184295113018123474" /></a>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-42580332813945248402008-04-01T07:14:00.000-07:002008-04-01T07:17:05.729-07:00long timeIt's been about a year and a half since I've posted here, and the world of tech writing blogs has not grown too much bigger. I still lament that most tech-writing discussion centers on the tools of the trade, rather than the craft of the trade. But maybe this time around I'll have something interesting to chat about.Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-1158240930065566262006-09-14T06:33:00.000-07:002006-09-14T06:35:30.080-07:00Thought of the dayPublishing and Technical Writing are two separate fields. The notion of a documentation department probably creates the needed umbrella for the two fields. It is my belief that you probably only have enough time to engage in either of the sides of documentation. Unfortunately, I believe that many corporations push their workers toward wearing both hats.<br /><br />As an example, I'm on a Framemaker listserv. I'm not sure why I joined exactly, but I've learned a lot. As someone who really loves technical writing, the difference becomes stark when the contributors to the list get all excited about getting Framemaker to make their lives easier - making the publishing aspect of the company's documentation needs accurate and efficient. Personally I'd rather concentrate on writing great docs - I'd publish to a .txt file if need be!<br /><br /><a href="http://technorati.com/tag/technical+writing" rel="tag" class="techtag">technical+writing</a> <a href="http://technorati.com/tag/technical+writer" rel="tag" class="techtag">technical+writer</a> <a href="http://technorati.com/tag/documentation" rel="tag" class="techtag">documentation</a> <a href="http://technorati.com/tag/Framemaker" rel="tag" class="techtag">Framemaker</a> <a href="http://technorati.com/tag/publishing" rel="tag" class="techtag">publishing</a>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com4tag:blogger.com,1999:blog-19005949.post-1157658643351332012006-09-07T12:47:00.000-07:002006-09-07T12:52:54.910-07:00poor facebookDisclaimer: I have never viewed or belonged to facebook.com.F or those who know, correct my errors, but facebook is similar to myspace (and livejournal), i.e. a social networking site.<br /><br />Facebook is getting hammered by a select set of critics charging that they are releasing person information about members. In actually it seems that Facebook has implemented RSS/whatever feeds of each friend-type user's page, such that any subscriber to the feed can easily view (or be alerted?) of page updates. (I think that the feed is placed directly on a user's home page… much like LJ friend’s lists)<br /><br />Now presumably Facebook, with its .edu bent, attracts a wide range of users, not necessarily the Internet elite. The Internet elite, heralding all things web 2.0, love when you can add technologies on top of each other to make for a more connected and collaborative online world. News feeds are one of these tools. So I find it funny that the implementation of a tool, which in the abstract can only do good, is being resisted so fervently by the <span style="font-style:italic;">rest of us</span>. (OK, i gotta say, I probably fall into the category of Internet elite)<br /><br />Only speculating, but the real error here is that the developers and product managers at Facebook were probably too personally involved in the web 2.0 scene to step back and think for a second that their user base wasn't.Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0tag:blogger.com,1999:blog-19005949.post-1154354537584801982006-07-31T06:58:00.000-07:002006-07-31T07:02:17.596-07:00survey: favorite technical writing taskI have a simple monday morning question to pose to all the technical writers out there:<br /><br />What is your favorite task or thing about being a tech writer? We take on 1000 roles, and going from idea for a document to a stack of papers (or file) in a user's hand requires many discrete steps. Which is your favorite step?<br /><br /><br /><br /><div class="techtags">Tech Tags: <a href="http://technorati.com/tag/technical+writing" rel="tag" class="techtag">technical writing</a> <a href="http://technorati.com/tag/technical+writer" rel="tag" class="techtag">technical writer</a> <a href="http://technorati.com/tag/documentation" rel="tag" class="techtag">documentation</a> <a href="http://technorati.com/tag/work" rel="tag" class="techtag">work</a> <a href="http://technorati.com/tag/fulfillment" rel="tag" class="techtag">fulfillment</a> <a href="http://technorati.com/tag/best parts" rel="tag" class="techtag">best+parts</a> </div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com1tag:blogger.com,1999:blog-19005949.post-1152646141039407042006-07-11T12:21:00.000-07:002006-07-11T12:41:13.006-07:00Woo, a pretty cool article entitled "<a href="http://www.reallylinux.com/docs/techwriting.shtml">Tech Writing in the Age of Open Source</a>" on <a href="http://www.reallylinux.com">reallylinux.com</a>. Overall a good read, and I'd like to comment on a few of Mark Rais's words.<br /><br />1. The Reader Feedback Loop. I believe that all TWs want user feedback. We want to make our work that much better, and the only way to learn how to improve is to elicit reader feedback. What Rais fails to realize is that in business and non-personally-motivated communities, most users are likely to grumble and move on after experiencing poor documentation. They aren't paid enough to share what they think.<br /><br />2&3. This is based on the assumption that your organization delivers its documentation primarily via the web. In all of my experience, this has not been the case. Maybe it's different for other people.<br /><br />4. Lots of points here:<br /><ul><li>Timing over perfection. I agree 100%, although Rais fails to realize that if you produce imperfect, technically inaccurate and misleading documents, your company can be held legally libel. OSS escapes this challenge. </li><li>"Although this emphasis on 'exceptional grammatical quality' may be a worthy trait, it is a worthless cause." I could not agree with this more. Good grammar is important, but devote a worthy amount of time to it, please! I think after years in the biz, we learn how to write in a quick, streamlined manner that gets around most grammatical challenges.</li><li>Honestly, TW projects usually lag behind the software development projects by a week or two at most. If this lag can be accepted (which I think it can in any context), I think that the timing issue isn't really so important. I’ve never seen documents lagging behind the software by months…</li><li>I don't know about this active voice nonsense, I really don't. All of my life I was taught that active is stronger than passive, and it certainly makes sense to me. Is Mr. Rais confusing person and voice, when he discusses what a global audience requires? Certainly globalized English is important to know. Does anyone out there have any tips on how to write this way? </li></ul><br /><a href="http://technorati.com/tag/technical+writing" rel="tag" class="techtag">technical writing,</a> <a href="http://technorati.com/tag/technical+writer" rel="tag" class="techtag">technical writer,</a> <a href="http://technorati.com/tag/documentation" rel="tag" class="techtag">documentation,</a> <a href="http://technorati.com/tag/OSS" rel="tag" class="techtag">OSS,</a> <a href="http://technorati.com/tag/linux" rel="tag" class="techtag">linux</a>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com1tag:blogger.com,1999:blog-19005949.post-1151958727515690232006-07-03T13:30:00.000-07:002006-07-03T13:33:38.833-07:00hrmI kind of jumped into Web2.0's blogging scene way too fast and never researched anything. So lets see if something like this, including tags, actually draws traffic to semicolon. :)<br /><br /><br /><div class="tag_list">Tags: <a href="http://www.technorati.com/tag/technical+writing" rel="tag nofollow">technical writing</a>, <a href="http://www.technorati.com/tag/technical+writer" rel="tag nofollow">technical writer</a>, <a href="http://www.technorati.com/tag/documentation" rel="tag nofollow">documentation</a>, <a href="http://www.technorati.com/tag/engineering" rel="tag nofollow">engineering</a>, <a href="http://www.technorati.com/tag/VoIP" rel="tag nofollow">VoIP</a>, <a href="http://www.technorati.com/tag/framemaker" rel="tag nofollow">framemaker</a>, <a href="http://www.technorati.com/tag/visio" rel="tag nofollow">visio</a>, <a href="http://www.technorati.com/tag/networking" rel="tag nofollow">networking</a>, <a href="http://www.technorati.com/tag/IP" rel="tag nofollow">IP</a></div>Writer Zerohttp://www.blogger.com/profile/13518938983838974113noreply@blogger.com0