I’ve just come across a new plugin developed by 224 team. It provides a Confluence macro that lets you embed a Google Wave into a Confluence wiki page. I’ve just got back from holiday, so I haven’t played around with the plugin much yet. But I’m blogging about it so that more people can try it out too. It’s cool to see this sort of development happening and even to get involved in the early stages. A friendly warning: The plugin is pretty new, so it’s best to try it out on a test installation of Confluence. To install the plugin: Download the JAR file from…
Technical Writing
-
ffeathers -- a technical writer's blog
-
Google Wave in Confluence wiki pages
31 Oct 2009 | 11:37 pm -
I got dragons and tweets in my documents
9 Oct 2009 | 8:51 pmYou may think you have problems, with the odd misplaced apostrophe or errant semi-colon in your documents. Well, there are dragons prowling around mine, and tweeting dragon slayers too! A few weeks ago some smart Atlassians had the idea of making it feel like fun to set up a number of our applications as an integrated Atlassian suite. (I work at Atlassian, makers of Confluence wiki, JIRA bug tracker, and other applications for software developers.) We’ve known for a while that it’s, uh, difficult to integrate our apps. In fact, people have used somewhat stronger words to describe… -
Yard table assemblage instructions
9 Oct 2009 | 4:57 pmThese “Yard table assemblage instructions” were included with a garden table we bought. Actually, the structure of the guide is good. There’s a list of parts and then the “how to”. It’s just the language that needs a bit of tender loving care. I love the way it degenerates towards the end, as if the poor author just gave up because it was too hard. Assemblage parts: 1.One piece of iron flower pattern glass (in midst have a hole). 2.Four table feet. 3.Two fixed stators. 4.Eight screws. 5.Eight screw caps. Assemblage method: 1.Use the screws and screw caps… -
WebWorks ePublisher for converting documents to Confluence wiki
3 Oct 2009 | 11:18 pmOver the past couple of weeks I’ve had the chance to experiment with WebWorks ePublisher, a set of tools that converts documents from Word, FrameMaker and DITA XML to a number of different output formats. One of those output formats is Confluence wiki. It’s been very interesting, so I thought I’d blog about it and see if anyone else wants to give it a go as well. I started off knowing a bit about what ePublisher can do, having attended a WebEx demo. But I had never used it. This was such fun! Most of this blog post is going to look like a “how to” guide, because… -
Getting content into and out of wikis
14 Sep 2009 | 12:04 amAs wikis mature, we’re using them for more complex business cases such as technical documentation, business analysis and project management. It’s becoming more and more interesting, if not essential, for wikis to support the import and export of content to and from other formats. Most wikis allow you to convert their pages at least to PDF and HTML. But what of other formats, and what about tools for getting content into wikis as well as out of them? For the past couple of months I’ve been writing myself notes whenever I see mention of such a tool. Now I’ve added a bit…
-
just write click
-
Consistency and community-generated content
4 Nov 2009 | 2:01 pmI’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome. Why consistency? You may not be a big fan, especially if you’re a creative type, because you appreciate when something interesting and new pops out at you. Unfortunately, you may be one of the few who appreciates something popping out while they’re trying to learn a task or evaluate a concept or analyze a pending… -
Twitter and conversation analysis – who’s here?
26 Oct 2009 | 9:27 pm“Hoosier,” the somewhat odd name for a native from Indiana, may have its roots in conversation. One of the stories is that when a knock from someone at the door rang out, the person inside would ask, “Who’s here?” and the greeting was shortened to “Hoosier?” Since I grew up in northern Indiana, my memories of it are fond and nostalgic. I’m particularly pleased that some of the researchers of Twitter and conversation analysis are at Indiana University, a lovely campus that I visited more than a few times. Is Twitter appropriate for conversation… -
Notes from WebWorks RoundUp 2009
20 Oct 2009 | 9:30 pmI attended two days of the WebWorks Roundup here in Austin this week and served on a few panels. I enjoyed signing books as every attendee got copies of books from XML Press. It had featured speakers like Tom Johnson and Stewart Mader as well as sessions with Lisa Dyer and Alan Porter to name a few. Here are my summary take aways from the sessions. Wiki adoption Stewart Mader is a wiki consultant, probably the most experienced, practical, and sensible wiki adoption expert available today. His message about wiki adoption resonated with me as I look for collaborative authoring solutions for our… -
How you learn to use Google Wave
12 Oct 2009 | 8:09 pmSince I write user assistance for a living, I’m naturally drawn to the devices the Google Wave team is implementing in order to teach people how to use Google Wave. For me, there were a few waves in my inbox from the start. First, Doctor Wave, impersonating a Bill Nye the Science Guy character appears in the “Welcome to Google Wave” wave as an embedded YouTube video, and points to different areas on the screen while embedded in a Wave. It’s a nice welcome and a great navigation aid to the user interface, very clever in that the perspective is as if he’s talking… -
Content curation – a manifesto
10 Oct 2009 | 12:33 pmThe phrase “content curator” was one I had to define in the glossary of my book. It seems now that content curator is an idea that others are writing about as well. RJ Jacquez, Adobe product evangelist, tweeted a link to an article about Content Curation on the site Social Media Today titled “Manifesto for the Content Curator,” written By Rohit Bhargrava. In it, he describes his definition of a content curator: “A Content Curator is someone who continually finds, groups, organizes and shares the best and most relevant content on a specific issue online.”…
-
one man writes
-
On taking notes
4 Nov 2009 | 12:53 amI have been remiss at writing new content for this blog, and whilst this topic isn’t one that I said I’d post about (those posts are coming, I promise), it’s something I was discussing yesterday and so is at the forefront of my mind. Like many people I still use pen and paper when taking notes, and regardless of the type of meeting I stick with three basic categories. [] Actions either for me or my team to do. Includes things that need done immediately or things which it would be good to do in the future. ? Questions on things I want to learn more about, which relate to my… -
What next?
29 Oct 2009 | 2:32 pmLast night, around 3am, I woke up. I lay there in bed wondering why I’d woken up and as my mind started to churn I realised I was very very awake. In flooded four things I’ve been thinking about for some time, all of which are related but I couldn’t quite make the connection. Last night I cracked it. Maybe. I’m still thinking it through but here are the four items in question: Single sourcing our documentation – and recent discussions with other areas of the company who could benefit from the same approach. Company Information Strategy – a simple pyramid… -
Author-it & Word
27 Oct 2009 | 4:54 amA teeny tiny gotcha that I thought I’d mention here. I can’t find explicit mention of it in the Author-it Knowledge Center and it’s tripped me up a bit. Quite simply, and I realise these will sound obvious, make sure everyone who is using Author-it is using the same version of Microsoft Word. My particular scenario has my laptop running Word 2007, making changes to the template, but when publishing from a machine running Word 2003, the footers weren’t being displayed despite the AutoText entry being available in the output Word document. Naturally I’m discovering… -
Dumping the manual
20 Oct 2009 | 12:46 amI honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase. It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies. Even now whilst we have a “documentation set” comprising several different user manuals, it’s… -
Selling ourselves
15 Oct 2009 | 1:32 amLike many, I struggle at times with a common perception, one which was highlighted to me yesterday by a colleague. Like most team leads/managers, I have a lot of tasks that aren’t purely focussed on the creation of information. I don’t do much technical writing, instead letting the guys in my team focus on that (they are better at it than me anyway) whilst I work around the edges of what they do, things like taking a document through a review with some SMEs and processing the output, or building a new output template, or proof reading some of their work. My team and I have a good…
-
Technically Speaking
-
Intellectual Property Responsibilities of Content Developers
13 Oct 2009 | 2:36 pmAs a technical writer, I develop content for the applications I’m supporting. Often that includes designing content, images, and multi-media to provide the best user experience possible. As content developers, however, we have a responsibility (both legal and moral) to ensure that the content we are using is being used properly and legally. We live in a world with lots of avenues to get content for our projects. Several websites specialize in searching for media that you can download and use in your product. Just because you can find it, however, does not mean you can use it. There are… -
Analysis of Team Design Review
7 Oct 2009 | 12:57 pmProbably most of you don’t know that I changed jobs recently, which is part of the reason I’ve been posting so infrequently. When you change jobs there is so much to learn, and it takes time. One of the benefits of my new job is that I’m working with an impressive team. I have great respect for every one of my team members. We have four technical writers, three trainers, and our manager. They are quite the group. We have Intermountain STC chapter president Ben Minson, the unstoppable Tom Johnson of I’d Rather Be Writing, and fellow Flare pro Derek Warren. -
The STC Crisis: the take of a “young” writer
22 Jun 2009 | 1:02 pmAs a “young” technical writer, I thought I might share some of my feelings on the STC crisis. First, a little background on me. I knew while I was in college that I wanted to be a technical writer after graduation. I switched to an English major for that purpose, and picked classes that gave me a “technical communication emphasis”. I joined STC while I was in college because I wanted to connect with people in my field. I got a chapter scholarship to attend a regional STC conference, and had a great time meeting people who did for a living what I was studying. When I… -
Flare 5 is now available
8 Jun 2009 | 9:38 amAccording to MadCap’s website, MadCap Flare V5 is now available for everybody! If you have a maintenance agreement, I guess that means you can expect your Flare V5 license to arrive shortly! If you want to know more about what is coming in the latest version, check out my pre-release blog post. -
Pre-Release Review of Flare V5
3 Jun 2009 | 1:00 pmSoon MadCap Software will be releasing the next major version in the Flare product line, Flare V5. I’ve been beta testing Flare 5 for a couple of months now, and there are some great new features in Flare 5 that you are going to love. In this review, I want to point out some of my favorite new features, as well as some of Flare 5’s other great enhancements. Let me begin by saying that I love Flare, and I think Flare 5 is a great enhancement on an already great product. I am biased; I’m a certified Flare instructor, have been a VIP in the Flare Forums for 2+ years, and am a…
-
The Content Wrangler
-
The Kindle 3 Parody: CollegeHumor.com Takes A Stab At Video eBooks
1 Nov 2009 | 12:19 pmeBook readers are making big news in the publishing industry and in businesses of all types around the globe. Organizations small and large are realizing that in addition to the products and services they offer for sale, they are also publishers. As a result of this realization, we expect to see all sorts of business-critical content released in a format that can be viewed on eBook readers and other devices (smart phones, netbooks, laptops, etc.) One of the most common eBook formats is PDF, which provides much more functionality than many people realize. Today, PDF supports 3D graphics,… -
10 Irresistible Potholes that Writers find on the Road to Globalization
28 Oct 2009 | 10:08 amBy Mike Dillinger, PhD, Translation Optimization Partners (with contributions from Laurie Gerber) Previously published in ClientSide News Mike Dillinger, PhDOptimizing the translation process has two basic components: improving the writers’ source texts and improving the translators’ process. For the moment, we’ll focus on the writer’s job. Dear Translator: Please remember that most writers never had any training at all about translation and usually know one lonely language. Many of them can only rely on the limited writing advice that they got in school. They’re never aware of how… -
Oops! When Web Forms Disclose Personal Information
27 Oct 2009 | 2:21 pmI received an invitation to download an Adobe sponsored whitepaper by IDG Connect (the self-proclaimed “premier IT knowledge base”). I was interested in the topic, so I clicked on the link provided in the email. As expected, my web browser populated the registration form for me. But, when I looked closer, except for the “email address” field, the rest of the form was populated with someone else’s information. I asked others to test this form for me, but they were unable to replicate my experience. I don’t have this user’s information on my laptop. I… -
What is Intelligent Content? And Why Won’t Scott Abel Shut Up About It?
12 Oct 2009 | 3:57 pmScott Abel, The Content WranglerMany of my readers have heard me preach about the value of intelligent content, as if up until now, all other content was dumb. Well, there’s a certain amount of truth to that. But, to understand this line of thinking, it might help to grasp the concept of intelligent content. Intelligent content is content which is not limited to one purpose, technology or output. It’s content that is structurally rich and semantically aware, and is therefore discoverable, reusable, reconfigurable and adaptable. It’s content that helps you and your customers… -
Linked2 Connects Adobe FrameMaker to Documentum: Interview with Jim Fettes, Millennium Consultants
6 Oct 2009 | 8:58 amTCW: Jim, thanks for talking with us today. Before we dive into the interview, tell us a little about yourself and the company you work for. JF: I have been in the high-tech industry for 28 years. The company I work for, Millennium Consultants, Inc. is a Technology company that specializes in: Software Quality Assurance, Software Development, Staffing, IT Security and E-Learning. TCW: You’ve got a pretty interesting mix of products, one of which is of particular interest to our readers. It’s called Linked2. Can you tell us briefly what it is and what it does? Linked2: Seamless…
-
I Came, I Saw, I Learned...
-
Acrobat 9: Keyboard Shortcuts Galore
3 Nov 2009 | 3:28 pmby David R. Mankin, the Acrobat Czar While casually scanning the constant flow of Twitter topics this afternoon, something caught my eye--a quick promise of a free collection of Adobe CS4 keyboard shortcuts brought me to the Adobe Student Hub. It seems that Adobe is offering substantial discounts on their software to qualifying students -- "Adobe Student Editions software is for use by higher education students only." Fair enough.The site is annoyingly noisy (IMHO), and you can turn off the crazy electronic throbbing noise by clicking on the tiny speaker icon on the left… -
Question of the Week: Adobe RoboHelp Projects... How Big is Too Big?
3 Nov 2009 | 3:26 pmQuestion: My team and I are preparing to work on projects in RoboHelp 8 and are looking into how to best publish the files. We're very interested in FTPing because it would give us the flexibility to publish on our own without depending on IT for deploying the !SSL files to the intranet (I have used FTP before, and it worked very well). However, we will need to request some server space so we can FTP our projects to an IIS server, but we are not sure how much IIS space to request. So, my question is, in your experience, is there an "average" MB per published project? In my own… -
Writing & Grammar Workshop: Department of Redundancy Department
3 Nov 2009 | 3:25 pmby Jennie Ruby "Double your pleasure, double your fun" may be a good thing when it comes to chewing gum, but in writing it may be a distraction--or worse--an error. Expressions such as past history, future prospects, and serious crisis are redundant, but so popular that many readers won't notice them.Redundancies such as a double negative (don't have no) or the reason why is because are noticeably wrong.In business or technical writing, stay away from is is and does is, as in "What it is, is larceny." Instead, eliminate the introductory clause and go with "It… -
Twitter Best Practices
2 Nov 2009 | 1:17 pmRJ Jacquez, Senior Product Evangelist at Adobe, is quickly becoming one of the best known and prolific TechCom and eLearning Tweeters around. He's had so much success with Twitter, RJ has created a running list of Twitter Best Practices.Says RJ, "This list has worked for me and I hope that it will work for you too. I will continue adding to this list, so please consider following me on Twitter @rjacquez for new updates to this list." -
Adobe Captivate 4: Shortcuts Anyone?
2 Nov 2009 | 1:13 pmby Kevin SiegelI can't tell you how many times I've been asked if there was a list of keyboard shortcuts available to make some of the cool things Captivate can do a little bit faster.There is, and here it is... File Menu Open Ctrl + O Close Ctrl + W Save Ctrl + S Import Audio To Slide F6 Preview Slide F3 Preview Project F4 Preview From This Slide F8 Preview Next 5 Slides F10 Preview In Web Browser F12 Publish Shift + F12 Print Ctrl + R Edit Menu Copy Slide Ctrl + C Duplicate Slide Ctrl + D Delete Slide Del Copy Background Ctrl + Shift + Y Select All Slides Ctrl + A Find and Replace…
-
I'd Rather Be Writing - Tom Johnson
-
How Microsoft Visual Studio Is Doing Help
7 Nov 2009 | 5:08 amThe following 10 minute video shows what’s new in the help system for the upcoming release of Visual Studio 2010 Beta 2. The key trends are as follows: Help is embedded in a browser because the browser is the predominant mode people use to find information. Search is the main method for navigating content. There’s no more table of contents or even index. When you choose a topic, you see contextual topics related to the topic you’re viewing. You can choose to include online content into the search. The help is “decoupled” from the Visual Studio application, so the… -
Podcast Roundtable for PodcampSLC Series
6 Nov 2009 | 1:05 pmI recently had the opportunity to participate in a podcast roundtable as part of a series to promote the upcoming Podcamp Salt Lake City, planned for March 26, 2010. Podcamp is a conference on podcasting and videocasting, with local presenters giving both beginning and advanced sessions in an informal setting. Guests on this round table show include Gregory Lemon, Drew Tyler, Thom Allen, and me. We recorded it at the Salt Lake Beta Loft, which is a space for freelance professionals to work and collaborate. Drew, who runs the Beta Loft, is a video genius and put together the video. Blog… -
Theme Parks and External and Internal Input
5 Nov 2009 | 9:41 pmThis week I’ve been on vacation in Florida, visiting my family and touring the theme parks — Seaworld, Disneyworld, and (soon) Busch Gardens. I used to live in Florida and would go to Busch Gardens all the time. But this week is more extreme. Our first day at Seaworld, I realized my theme park endurance was poor. The next day at Disney was much better, even with just 6 hours of sleep the night before. The second time around Seaworld (of course one day wasn’t enough) was like stopping off for a brief jaunt at the mall, except when we temporarily lost our daughter, which sent… -
Podcast on the Seven Deadly Sins of Blogging
5 Nov 2009 | 8:59 amDownload MP3 Length: 1 hour 45 min. Over the last month, you’ve been seeing various posts on my site about the seven deadly sins of blogging (being fake, irrelevant, boring, unreadable, irresponsible, unfindable,, and inattentive). I mentioned at the beginning of my seven deadly sins series that I was preparing for some upcoming presentations on blogging. I first presented on the Seven Deadly Sins of Blogging at WebWorks Roundup 2009. I gave a similar presentation to the STC-Suncoast chapter (in Tampa, Florida) last night. The latter one I recorded. While the content of both… -
The Long Tail of Online Profitability
3 Nov 2009 | 9:27 pmLast week I listened to David Peralty give feedback to Jeff Chandler about his WordPress Weekly and WPTavern.com projects (see episode 75). David praised the community and visibility that Jeff had created through his weekly podcast and forum, in addition to his WPTavern.com site, but noted that he was aware Jeff hadn’t reached the monetization goals he hoped to achieve. In other words, Jeff has done a tremendous job at creating a community and audience for his site and podcast, but he hasn’t found a way to make real money off his activities. If you monetize your online activities, you can…
-
Your Writing Dept Blog
-
More InfoPorn: Our new favorite site
21 Oct 2009 | 9:07 pmI’ve said it before and I’ll say it again. I love InfoPorn. This is what we consider the presentation of what could be considered dull information in interesting and fascinating presentations. Trust me, these are not your typical MS Excel bar charts. The site Information is Beautiful seems to have it all for the infoporn addicted. [...] -
Technical Writing Jobs: Salary Information
8 Oct 2009 | 10:25 amInteresting reading: United States Bureau of Labor Statistics (BLS) Occupational Employment Statistics (OES) (free and available to the public) about how technical writers are paid. This provides some interesting reading for anyone wishing to determine where their state ranks regarding salaries or job availability. There’s a lot of information available, so explore the site and [...] -
Where To Go To Become a Tech Writer or To Find One To Hire?
5 Oct 2009 | 9:28 pmBy Tom Guarnera Related posts… How Do I Become a Technical Writer? What Are the Characteristics of a Good Technical Writer? Finding a single place to learn about Technical Writing is not the easiest task. Because of this, it is even trickier to find a good source for locating potential candidates for the job. Many writers seem to be [...] -
What Are the Characteristics of a Good Technical Writer?
30 Sep 2009 | 7:37 pmBy Tom Guarnera Related posts… How Do I Become a Technical Writer? Where To Go To Become a Tech Writer or To Find One To Hire? In my previous post, I started to address the question, “How Do I Become a Technical Writer?” I concluded that most writers do not set out to go into this field, but more [...] -
How Do I Become a Technical Writer?
28 Sep 2009 | 11:47 amBy Tom Guarnera Related posts… What Are the Characteristics of a Good Technical Writer? Where To Go To Become a Tech Writer or To Find One To Hire? Tech Writing News… U.S. Government Acknowledges Technical Writers As Distinct from All Other Writing Professions I have recently seen a number of discussions asking technical writers if they chose to become a writer [...]
-
Gryphon Mountain Journals
-
Clear, Common Language Leads to User Success
5 Nov 2009 | 4:27 pmA huge problem for projects is the lack of a common language between the developers and the users. When my colleague and I were preparing a presentation for an internal conference on this subject, he said something that has stuck with me. He said, “The goal of the project is to make the user successful.” I added to that: It’s not to write code or validate code. It’s not even to ship a product or make money (of course, this last one is especially true in a non-profit organization). At least, it shouldn’t be these things. The goal of a project is to make the user… -
Weed out Irrelevant Content
28 Oct 2009 | 1:00 amIn a recent iteration review meeting, the team discussed with the customer the progress made over the previous three weeks. In these meetings, we also discuss risks and demonstrate what has been accomplished. The Enthusiastic Developer Sometimes, the work performed is on the background functions; while it affects the user interface, it’s not something the developers can demonstrate through the interface. In this particular meeting, one of the developers explained the theory behind something that was very technical in nature and happening behind the scenes. Developers are great, and they… -
Careful Observation Adds to Effective Writing
26 Oct 2009 | 5:28 pmWhen I was a kid, I wanted to be an animator. I loved drawing Looney Tunes characters. I did it so much that I can still draw them, years later, though having done it seldom in the interim. Of course, I changed my mind and decided to be a writer. I would still draw and doodle, and I even had a cartoon strip in the university newspaper later, but I tended to write a lot more than draw. A couple of weeks ago, I decided that I wanted to get back to drawing on a regular basis. The best way to fit that into my schedule and make sure I actually did it was to spend a few minutes each night sketching… -
Where Usability and Documentation Meet
20 Oct 2009 | 8:05 pmLast week, IT groups in the organization held a conference so that we could share techniques and best practices while saving the money it would take to send hundreds of people to external conferences. Because of the different roles represented aside from developers and testers, I had enough topics other than things like Java and test automation to keep me busy throughout the two days. One of the sessions I attended was the basics of usability presented by a usability specialist and an interaction designer. The session included an exercise that illustrated why usability testing is important… -
The Long and Short of Blog Posts
14 Oct 2009 | 5:10 pmOne of the pieces of blogging advice you may get is to keep posts short. People don’t have long attention spans, and they flit from piece to piece of information without staying long at any particular one. Writing short posts can be nice also because you can write without making a big time commitment. Still, I personally prefer to write longer posts much of the time. Most of the time, “longer” means just a few paragraphs, but at other times, I like to use the post to explore my thoughts. It’s hard to get into the guts of an idea or concept in 100 or 200 words. Just…
-
HelpScribe
-
White paper writing | Strategies for success
29 Oct 2009 | 3:51 pmWhite papers are a fundamental part of your marketing arsenal. And if you think technical writers don't need to worry about marketing, read on to see why white paper writing is an essential skill, and how to turn a ho-hum paper into a killer communications tool. If you are a freelance or contract technical writer, a strong white paper can help you land new clients. The primary difference between contractors who succeed and those who fail is that the winners are better at selling their services. Sure, you're a highly skilled technical writer. But if you can't explain to clients why your… -
The Jetsons, and technology running amok
11 Oct 2009 | 5:52 pmTonight I'm watching The Jetsons with my kids. It's a very enlightening cartoon. In fact, I've never seen a better argument for the need for technical writers. Every morning George is flung from his bed and conveyed through a slew of machines that dress, groom, and feed him before flinging him into his jet car and sending him on his way. (I could REALLY use a setup like that.) Unfortunately, these contraptions often fling poor Jetson into a wall, or leave him trapped in his bed matress. Responsible engineers would never build such machines. However, accidents happen and products malfunction. -
Training manual DOC files
11 Oct 2009 | 5:14 pmWriting a manual from scratch? A training manual template in DOC format will help you produce a high quality document using Microsoft Word. You can get professional templates using the link below. GET TRAINING MANUAL DOC TEMPLATES - The "User guide", "Training plan", or "Employee handbook" templates might serve your needs. A template will lay out the format for your guide, prompt you for essential content, and help achieve a professional look and feel. For information on writing your manual, try the following post. How to write training manuals -
How to archive documents
30 Sep 2009 | 5:14 pmKnowing how to archive documents is essential to an efficient workflow. Think about it; you work hard to create the documents your organization needs to be effective. Why risk losing that hard work? Archives ensure that you can recover any lost documents, and make it easier to track the specific details of your project the next time you work on it. Here are a few tips for creating an effective archive for your documents. Create a readme file and store it with your project files. The readme should also be archived along with the rest of the project. Readme files should contain essential… -
Document automation - Word
27 Sep 2009 | 8:21 amThis article contains tips and getting-started information for documentation automation with Microsoft Word. MS Word has incredibly useful VBA features that allow you to automate routine documentation tasks. You can use the Record Macro feature to automate many repetitive actions, such as retagging paragraph styles, searching and replacing content, and so on. For advanced automation, use the Visual Basic Editor. The editor has many GUI features to assist you in writing code for complicated procedures. Why automate? Repetitive action is costly. How many hours does your documentation team spend…
-
technically speaking
-
Halloween Demo Day
30 Oct 2009 | 9:46 amIt’s a tradition: Every year on Halloween (or as close to it as the work week will allow), tons of LabVIEW developers set up shop at their desks and demonstrate features or products they’ve been working on to all comers. The email goes out to the entire company (in Austin, anyway) and for two hours, (most) work stops as people come by to check out what we’ve been working on. Today’s that -
Preview of LabVIEW 1.0, 1986
26 Oct 2009 | 9:53 amIn the comments on my last post, Yair pointed me towards this preview of the LabVIEW 1.0 beta, all the way back in 1986. Enjoy! -
Interesting Articles
26 Oct 2009 | 8:02 amHere’s a review of the original Macintosh, done in 1984. It’s amazing to read this now with 25 years of perspective and realize both how different it was and how similarly things still work today. But even back then some people seemed to “get it”. When LabVIEW was first released in 1986, it was for the Mac, because that was the dominant graphical platform of the day, and LabVIEW is -
Interesting Articles
23 Oct 2009 | 1:59 pmI find myself reading a lot of tech news sites. I sometimes email these links out to developers or other technical writers if they are interesting or have applications to LabVIEW/NI, but I figured, why not share them with the world?Here's are a few things I came across lately:Don't offer preferences to users if you don't have to. I think about this sometimes as we design software here ... -
Leica & LabVIEW
13 Oct 2009 | 11:46 amLeica makes some of the highest-quality, precision-engineered cameras in the world. WIRED magazine recently caught up with them and took a tour of their facility in Solms, Germany. In one of the shots, you can see a LabVIEW application (designed by Ramitek GmbH) being used to test the M9, Leica's newest camera. It's kind of awesome to see LabVIEW being used to help control tolerances as fine as
-
CyberText Newsletter
-
A graphic that’s worth a thousand words
6 Nov 2009 | 2:12 pmThe other day, @KathySierra tweeted about this website. All I can say is ‘Wow!” What a terrific use of a graphic to explain the differences in size between small, common objects (e.g. grain of rice) and things such as human eggs, viruses, etc. Use the slider on this web page from the Genetic Science Learning Center at the Univeristy of Utah (http://learn.genetics.utah.edu/content/begin/cells/scale/) to get the full effect. Posted in User experience, Websites -
Euphemism for the sack
5 Nov 2009 | 1:47 pmYesterday I was editing an annual report for a small company, and came across these sentences in the “People” section: Some business restructuring also occurred across [the organization] to manage costs in response to the economic recession leading to an increased proportion of non-voluntary turnover on previous years. Management is closely monitoring turnover in line with our objective to maximise commitment and retention of our people. Um, hello? Isn’t ‘non-voluntary turnover’ a euphemism for the sack?? And if management forced some people to lose their jobs… -
Still supporting multiple versions of IE?
4 Nov 2009 | 2:12 pmIf you still have to support multiple versions of Internet Explorer, then you’ll want to take a look at this Smashing Magazine article about how IE 6, 7 and 8 treat various elements of CSS: http://www.smashingmagazine.com/2009/10/14/css-differences-in-internet-explorer-6-7-and-8/ And for those who scoff at the idea of anyone still using IE6, I’m currently working for a large global corporate where they’ve only *just* changed from IE6 to IE7. And some people there are still on IE6. [Links last checked November 2009] Posted in CSS -
Captivate: Change the autotext for captions
3 Nov 2009 | 1:14 pmOne small thing that’s annoyed me about Captivate ever since I started using it to create software demos is the default text. It starts off being a proper sentence, but doesn’t have closing punctuation (e.g. Select the [blah] menu). I’ve never bothered to investigate if I could change it — as I said, it’s a small annoyance. However, I’ve found out how to change it, based on a tweet from R Jacquez at Adobe. And it’s really simple. Go to C:\Program Files\Adobe\Captivate[version#] (or wherever your Captivate program files were installed). Find the RDL… -
Word: Quickly moving between headers and footers
2 Nov 2009 | 1:03 pmScenario You have a long document, or a large one filled with lots of big images, a mix of landscape and portrait pages, lots of section breaks, etc. You need to do stuff in the headers and footers (add/remove text, shift tabs, insert page numbers, adjust page margins etc.), but skipping from one header/footer to the next takes longer than you’d expected. Solution Hide the main document while you’re working in the headers/footers. You should find that you can skip between them really quickly once you do that. Turn on the document display after you’ve finished making your…
-
A Tech Writer's World
-
H1N1 A1 Confusion
2 Nov 2009 | 11:18 amThe media's endless drive for ratings has us all convinced we're about two minutes away from certain death. To be sure, the H1N1 virus (the artist-virus formerly known as "Swine Flu") can be lethal. But let's have some perspective: more people will die from the regular flu than this nasty variant. More will also die from car accidents, obesity, alcohol, smoking and many other plagues, but why let relevant comparisons get in the way of a juicy news story?To Save Your Life, Please Take a NumberThe latest news concerns the vaccine production problems. Contrary to earlier reports where the… -
The Doc Whisperer
27 Oct 2009 | 8:52 amI could certainly use dog trainer Cesar Millan. Our two-year old labradoodle Jessie is a bit of a mess. She often begs for food, and thinks nothing of resting on The Forbidden Couch. But compared to the dogs featured on Milan's show, The Dog Whisperer, she's Lassie.The Dog Whisperer is a unique reality-TV program. In each episode, we're introduced to a new insane animal and its even more insane owners. Dogs with a wide variety of behavioural and disciplinary problems are featured. Before this show, I would never have believed a dog could have OCD (obsessive compulsive disorder).Millan… -
Tech Writing, From A to Wii
23 Oct 2009 | 7:16 amMy wife asked me if we're ever going to buy a game console. In my worst French I mumble, "Oui". "We're getting a Wii!?!" she cries, " Woo-hoo!" I cannot Undo my misunderstood utterance.The good news is that Nintendo recently lowered the price of its popular gaming unit. The bad news is that the unit represents only a fraction of the total price. Once you're done adding accessories (such as the Wii fitness board, extra controllers, other games, extended warranties and taxes, you end up with a purchase price approaching that of a small car. But, oh boy, is it worth it.A brief disclaimer -… -
Catch the Wave
20 Oct 2009 | 9:54 amOutdated is a word coined by manufacturers to convince people the shiny new products they purchased six months ago and which work perfectly are now useless. However, once in a while, a new product comes along that really does make the current version practically obsolete. Google Wave could be just such an application.Google Wave is difficult program to describe, but is essentially a cutting edge communication application that's a combination of email, instant messaging and collaborative editing. Because Google Wave is so different than anything before it, the best way to learn about it is to… -
He Said/She Said
5 Oct 2009 | 11:21 amHere's a word puzzle for you: which pronoun (he or she) would you use to describe a person who has had a sex change? I ask this because I recently read a news article about a female teacher who underwent such an procedure. The teacher now considers himself?/herself? as a man. (Oy - I'm already running into trouble here.) However, the school (a religious one) still views this person as a woman. The author of the article used the title Mr. and the pronoun he when referring to the teacher. Is this correct?You see the catch-22 here. By using the word he, the writer accepted the position of the…
-
UAX (User Assistance Experience)
-
Energy in; energy out
30 Oct 2009 | 5:05 amOK, be prepared for Dante's 6th inner ring of metaphor Hell.I broke down and took a by-gawd Dobro lesson this week. I figure it's time to get serious about my music so I paid this guy $100 for a three-hour Vulcan mind-meld of Musical Theory 101. Never touched my guitar. (He got interrupted, though, so I did get to play his $5000 Dobro for about 20 minutes while he handled a domestic emergency.)So -
Talk Your Walk
16 Oct 2009 | 6:00 amI know the title of today's blog seems backwards, but that's the point I want to make. It is not at all unusual to find situations where a person says one thing and does another. In Action Science, that is called a gap between a person's stated beliefs and their theories in use. In common practice we say that someone isn't "walking the talk" with the implication that the problem is in the -
Moron Holes
14 Oct 2009 | 5:02 amMy buddy, Miranda, is a gamer, and she showed me a new one that allows the participant to shoot a hole into a wall that sort of bypasses normal space and time limits and lets the player emerge, for example, on the the other side of an otherwise uncrossable chasm. Cool.I think a similar device explains how some people can jump from assumption A to a logically inaccessible conclusion B--they're -
Screen Shots in Documentation
7 Oct 2009 | 6:01 amSometimes someone gives me documentation that "so and so" put together for his IT group that tells them how to install our product. Generally, the purpose is to show me how "real users" want to see documentation. Invariably it is a 32-step procedure with a screen shot in every step.Well, obviously, the writer in not familiar with Robert Horn or the demands for accessibility and globalization that -
State of the Ark (part 2)
6 Oct 2009 | 4:49 amAs I said in an earlier blog, "state of the ark" is my phrase for when I think I am on the leading edge of technology when in fact I'm back among the late majority or laggards.One of the problems with playing a Dobro all by yourself is that the instrument is really suited to provide accents and solo snippets. But I'd look a bit stupid standing in my den tapping my foot doing nothing then
-
TechScribe software documentation
-
Technical writing newsletter 33: October 2009
19 Oct 2009 | 6:00 amThe latest news from TechScribe. Issue 33 covers the use of international English to decrease translation costs, the quality of machine translation, Globish, and interface design. -
Globish the world over: a review
12 Oct 2009 | 10:00 amReview of 'Globish the world over'. Authors: Jean-Paul Nerrière and David Hon. Published 2009. English is important for international business, but English is a complex language. Globish is a method of simplifying English to make English easy for non-native speakers. Globish is a subset of the English language that has 1500 basic words and a simple grammar. -
ISTC online groups, summer 2009
2 Oct 2009 | 6:00 amISTC online groups. This review covers Scrum methods in technical communication, a new Twitter Group for technical communicators, and tax investigation insurance. -
International English gives satisfactory machine translation into Spanish
1 Oct 2009 | 6:00 amAn English article was translated into Spanish by Google Translate. Professional translators evaluated the machine translation for fluency and for accuracy of meaning. The quality of the machine translation is satisfactory. -
Technical writing newsletter 32: August 2009
10 Aug 2009 | 6:00 amThe latest news from TechScribe. Issue 32 covers how to decrease translation costs by using international English, and software to simplify the software localisation process.
-
Cherryleaf Technical Authors Blog
-
Microsoft Help Viewer - New Help System in Visual Studio 2010
6 Nov 2009 | 1:18 amIn this video, Ryan Linton, a Senior Program Manager on the Library Experience Team, describes the new Help system in Visual Studio 2010 Beta 2. [[ For the full article, see http://www.cherryleaf.com/blog.htm]] -
Managing a documentation project successfully - more jelly and ice cream
2 Nov 2009 | 3:03 amThis video on simplifying business, using the metaphor of organising a children’s party, made me smile and consider how successful documentation projects are managed. The presenter is... [[ For the full article, see http://www.cherryleaf.com/blog.htm]] -
Did technical documentation play a role in the White House’s decision to move to Drupal?
28 Oct 2009 | 1:04 amThe reasons for the White House’s decision to run its Web site, whitehouse.gov, on the open source content management system Drupal are being discussed on various Web sites. Alongside... [[ For the full article, see http://www.cherryleaf.com/blog.htm]] -
Managing a documentation project - a guide (and a test of Camtasia)
23 Oct 2009 | 5:04 amThis a short video overview of managing a documentation project. It’s something we put together as a test of some of the functionality of Techsmith’s Camtasia software. [[ For the full article, see http://www.cherryleaf.com/blog.htm]] -
Why are there so few UK technical authors on Twitter?
23 Oct 2009 | 12:59 amAt a rough guess, there no more than 20 UK technical authors using Twitter on a regular basis. Given the Social Web is going to play an increasing role in User Assistance and Customer Support,... [[ For the full article, see http://www.cherryleaf.com/blog.htm]]
-
Communications from DMN
-
Weekly links roundup
6 Nov 2009 | 2:40 amAn useful document covering how to index effectively in DITA (it’s in Word format) The basics of printing and prepress — yes, some companies still print their documentation How to effectively respond to criticism Seven steps to clear techncial writing Do you write in Globish? 10 potholes that writers find on the road to globalization Documentation review: get it done! To a man with a hammer everything looks like a nail -
Tech writing and the Free Software Open Source Symposium
4 Nov 2009 | 2:45 amLast week, I spoke at the Free Software Open Source Symposium (FSOSS) at Seneca College here in Toronto. It was an interesting experience, partly because this was the first Open Source event I’ve been to in quite a while, and the first time I’ve spoken to an audience of people involved in Open Source development and tech writing. On top of that, my presentation was one of three back-to-back sessions on technical writing. I was in the middle of two very good talks. Here’s what was said. The 4th dimension: documentation that enhances the user experience First up was Beth… -
Listen to the radio
2 Nov 2009 | 2:45 amRadio and documentation. It sounds like a strange, if not incompatible, mix. But if you think about it for a moment, the parallels are staring you right in the face. When writing documentation, my ideal model is a good radio report. Sounds kind of strange, doesn’t it? If you think about it for a moment, though, a radio report has all the elements of a good piece of documentation: It’s short and to the point Where necessary, it contains just enough background to orient the listener It contains all the important facts, compressed into small space in time When crafted properly,… -
A quick hit of news
31 Oct 2009 | 7:52 amYesterday, I attended the Free Software and Open Source Symposium at Seneca College here in Toronto. It was a very interesting and enlightening time, and the first time that I’ve spoken to an audience comprised almost completely of people involved in Open Source. I was pleasantly surprised that there wasn’t just one but three sessions on technical writing. In between everything else that I need to do over the next few days, I’ll be tapping out a report on two of those sessions — they’ll be published in this space on Wednesday. If you’re interested, take a… -
Weekly links roundup
30 Oct 2009 | 3:30 amA look at some Open Source alternatives to tech pubs tools Wondering what the new currency in the digital age is? Trust Here are three ways to be professional when using mobile apps If you’re a freelancer, you might want to read about some contract dos and don’ts A few trends and ideas in the tech comm world Some instructions you probably don’t need
-
Core Dump
-
Mars close up
7 Nov 2009 | 4:49 amNASA's Mars Reconnaissance Orbiter has returned some remarkable pictures of Mars from orbit. They're eerie, beautiful, and important from a scientific point of view. What's also notable is how similar portions of Mars look to portions of Earth, particularly the deep deserts of Saudi Arabia or high mountain plateaus. As usual, the large presentation of the Big Picture blog makes these images -
Video of new Microsoft Help system
6 Nov 2009 | 8:48 amHere's a video of a Microsoft program manager explaining the new help system in Visual Studio 2010. -
If you have a Google account, look at Dashboard
6 Nov 2009 | 3:03 amIf you have a Google account (in other words, if you use Google Docs, GMail, Blogger, and so on), you'll want to look at the new Google Dashboard, which puts all of the settings for your Google applications on one page. -
Lonely Lander
5 Nov 2009 | 3:49 amHere's a rather poignant photo. Taken from Martian orbit, it shows the Mars Phoenix Lander, sitting in a field of rocks covered in carbon dioxide frost. If NASA is very, very, lucky, they may be able to revive the Lander come Martian spring. -
Tech writing and the Free Software Open Source Symposium
4 Nov 2009 | 8:36 amLast Friday, my colleague, Scott Nesbitt attended the Free Software Open Source Symposium at Seneca College. There were three presentations on technical writing and open source, one of them given by Scott. He's written a post about his experience at the symposium, including summaries of the other writing-related presentations. It sounds like it was an interesting day, and hopefully the
-
Tech Writer News (Elephant)
-
Being Proactive - Finding Freelance Technical Writing and Editing Opportunities
1 Nov 2009 | 1:56 pmProfessional conferences and workshops are great opportunities for freelance technical writers and copy editors. The presenters often need your professional services andMore... -
Resilience Tip - Control, Where is it always possible?
27 Oct 2009 | 12:16 pmHaving a sense of control is a critical part of responding resiliently. Humans tend not to like the feeling of being blown around by the winds of chanceMore... -
Job Fair - Date moved to December
27 Oct 2009 | 11:57 amPeople & Computers’ annual job fair for Israeli High Tech Professionals will be held at Airport City on December 8th 2009. This is useful for anyone looking for a high tech job in Israel, in particular people who are in:More... -
Call for Papers (SwSTE 2010 IEEE Conference)
24 Oct 2009 | 5:29 amSwSTE 2010 is a biennial International IEEE Conference held in Israel (Herzelia on June 15+16 2010). It is a very professional and prestige conference, which interests and draws approximately 300 participants from the Israeli Hi-Tech industry. Click here to download Call for Papers...More... -
Translatable but Debatable ביצוע, לבצע
19 Oct 2009 | 11:17 amAs the champion high-jumper clears the bar, the sportscaster cries out: — which is to say, what a thing-doing. The English language has some theoretically fine translations for , but connotations are a problem. You could say what an accomplishment, but that would express the connotation that he did something difficult, not that he did it well or elegantly. This series of columns will be presenting one hard-to-translate Hebrew word at a time for discussion, and we’ll start with (or ). You’re encouraged to add your comments at the end of the column, but please stick to the…
-
Answers for All
-
Technical Communication: Design or Content?
24 Oct 2009 | 9:46 amHow is the role of technical communicators changing? What skills should we be focused on for future success? With content coming from many sources and contributors throughout the community, technical communicators can feel threatened. For many years, we were the sole developers of content, carefully crafting each phrase to deliver information clearly and concisely. [...] -
Building a Valuable Conference
8 Jul 2009 | 12:43 pmI am currently part of the program team for the 2010 STC Summit in Dallas, Texas. We are working together to make sure we create a quality conference program for all attendees. The real question is…what makes a great conference? I have attended many conferences over the years, and I have helped to organize [...] -
Learn How Much You Don’t Know
27 Jun 2009 | 5:53 pmIf you have seen The Matrix, you may remember the scene where Neo awakens in his “power cell” cocoon, looks out at all the other cocoons, and realizes how much he never knew was happening around him. This scene raises the point for me that…the more you know, the more you know you don’t [...] -
Technical Communication Trends and Ideas
13 May 2009 | 2:47 pmTechnical Communication continues to change as we find new ways to meet the needs of our audiences. I have attended several conferences recently and discussed several of the latest trends with other technical communicators. This article provides a quick list of several of these trends and ideas: Wikis are becoming more widely used as [...] -
Attend a Conference without Attending
12 May 2009 | 11:14 amBoth the WriterUA conference and the STC Summit in 2009 have proved that you can attend a conference without being there. Don’t get me wrong…there is a lot of value from being involved in the discussions within the program sessions. However, Twitter and ScribbleLive provide several important ways for us to share ideas [...]
-
User Assistance
-
Energy in; energy out
30 Oct 2009 | 5:05 amOK, be prepared for Dante's 6th inner ring of metaphor Hell.I broke down and took a by-gawd Dobro lesson this week. I figure it's time to get serious about my music so I paid this guy $100 for a three-hour Vulcan mind-meld of Musical Theory 101. Never touched my guitar. (He got interrupted, though, so I did get to play his $5000 Dobro for about 20 minutes while he handled a domestic emergency.)So -
Talk Your Walk
16 Oct 2009 | 6:00 amI know the title of today's blog seems backwards, but that's the point I want to make. It is not at all unusual to find situations where a person says one thing and does another. In Action Science, that is called a gap between a person's stated beliefs and their theories in use. In common practice we say that someone isn't "walking the talk" with the implication that the problem is in the -
Moron Holes
14 Oct 2009 | 5:02 amMy buddy, Miranda, is a gamer, and she showed me a new one that allows the participant to shoot a hole into a wall that sort of bypasses normal space and time limits and lets the player emerge, for example, on the the other side of an otherwise uncrossable chasm. Cool.I think a similar device explains how some people can jump from assumption A to a logically inaccessible conclusion B--they're -
Screen Shots in Documentation
7 Oct 2009 | 6:01 amSometimes someone gives me documentation that "so and so" put together for his IT group that tells them how to install our product. Generally, the purpose is to show me how "real users" want to see documentation. Invariably it is a 32-step procedure with a screen shot in every step.Well, obviously, the writer in not familiar with Robert Horn or the demands for accessibility and globalization that -
State of the Ark (part 2)
6 Oct 2009 | 4:49 amAs I said in an earlier blog, "state of the ark" is my phrase for when I think I am on the leading edge of technology when in fact I'm back among the late majority or laggards.One of the problems with playing a Dobro all by yourself is that the instrument is really suited to provide accents and solo snippets. But I'd look a bit stupid standing in my den tapping my foot doing nothing then
-
Writer River
-
Freelance Contracts: Do's And Don'ts Smashing Magazine
30 Oct 2009 | 12:47 pmLink courtesy of Scott Nesbitt. -
25 Useful Linux and Unix Cheat sheets @ Techie Blogger
25 Oct 2009 | 11:01 pm -
Embedded user assistance
24 Oct 2009 | 7:56 amAn excellent article on embedded help. -
Top Technical Writing Blogs
23 Oct 2009 | 9:03 amNice list of "top" tech writing blogs. -
UAX (User Assistance Experience): Screen Shots in Documentation
23 Oct 2009 | 9:01 amGood analysis of when to use screenshots in documentation
-
EServer TC Writing
-
Screencasting for Dummies (and Smarties)
6 Nov 2009 | 1:46 pmWith so much training being done on computers (along with other tasks being done while training is taking place on that same computer), it’s important to know some best practices for developing training and other modules with screencasts. Amy Tehan demonstrates tips and tricks for making an effective screencast that will hold the viewer’s attention and get the message across. Tehan, Amy -
Listen to the Radio
4 Nov 2009 | 1:02 pmRadio and documentation. It sounds like a strange, if not incompatible, mix. But as Scott Nesbitt explains, an ideal model for writing documentation is a good radio report. Nesbitt, Scott -
The Origin of Personas
4 Nov 2009 | 1:02 pmThe Inmates Are Running the Asylum, published in 1998, introduced the use of personas as a practical interaction design tool. Based on the single-chapter discussion in that book, personas rapidly gained popularity in the software industry due to their unusual power and effectiveness. Had personas been developed in the laboratory, the full story of how they came to be would have been published long ago, but since their use developed over many years in both my practice as a software inventor and architectural consultant and the consulting work of Cooper designers, that is not the case. Since… -
What's Your Customer's Persona?
4 Nov 2009 | 1:02 pmUsing "personas" forces us to think carefully about who our customer is for each product — what they need and want and how they'll use it. We've come up with a few personas, and each one has a name and personality. Even for a book on business planning, for instance, "Sally Startup" has different needs than does "Vic Venture." Abrams, Rhonda -
Getting from Research to Personas: Harnessing the Power of Data
4 Nov 2009 | 1:02 pmThe usefulness of personas in defining and designing interactive products has become more widely accepted in the last few years, but a lack of published information has, unfortunately, left room for a lot of misconceptions about how personas are created, and about what information actually comprises a persona. Although space does not permit a full treatment of persona creation in this article, I hope to highlight a few essential points. Goodwin, Kim
-
David Barnes @ Packt
-
Why the free availability of Unity3D and Unreal Development Kit has me nostalgic for my childhood
6 Nov 2009 | 8:50 amLike many skinny boys my age, the first computer book I ever read looked something like this: Looking back, it's easy to be cynical about these titles. Each book contained a whole selection of games. You'd get a few pages of code (a lot to type on a ZX Spectrum keyboard at the age of 9), virtually no explanation, and a lavish watercolor picture supposed to illustrate the game play. When you'd got the whole game typed in, you'd run it and discover that the game consisted of a few lines of plain text. Most of them didn't even use color. One game I remember was called "Archery". I was excited to… -
Amazon Turns Twitter into a Marketplace - Are You Concerned? (I'm not)
4 Nov 2009 | 7:59 amIf you're an Amazon Affiliate that is. You can now "tweet" Amazon books and get an affiliate link posted to Twitter nice and easily. I guess you could already do this by shortening the affiliate URL yourself -- but Amazon's now made it that little bit easier. RRW isn't happy, uses words like "spam" here: http://www.readwriteweb.com/archives/amazon_turns_twitter_into_a_marketplace.php -- seems a bit much when most people just get a bit of pocket money out of Affiliates. Permalink | Leave a comment » -
Help $TYPE_OF_PERSON be awesome at $THING (via @kathysierra)
3 Nov 2009 | 2:52 amKathy taught me that if you can’t explain your mission in the form, “We help $TYPE_OF_PERSON be awesome at $THING,” you are not going to have passionate users. What’s your tagline? Can you fit it into that template? via joelonsoftware.com This is the perfect single-sentence pitch for any book or educational product. It captures the target audience and the goal of the book in a few short, compelling words. The trick is to define each of those variables in the most specific, vivid way that you can -- and then let that mission drive everything about the book's content and approach. Not… -
Ever struggle to understand grammar rules? Don't worry, the teachers don't get it either...
3 Nov 2009 | 2:43 amMore from Geoffrey Pullum's Language Log. Well known grammar and writing rules books often written by people with no clue about the rules of grammar. Looking for a job? How about one where you set your own hours, you don't have a boss, you have nothing to do but write at your own pace, you end up receiving fat royalty checks, and you don't have to know anything at all about the topic that you write about? The job is to write non-fiction (textbooks and handbooks), only it's OK if you don't have a clue about the subject matter. One word about your new career (and it's not… -
Nerdview: It's the TAM LED, stupid...
3 Nov 2009 | 2:41 amOver at Language Log, Geoffrey Pullum moans about user manual diagrams with meaningless labels. Watch out for nerdview -- look at everything from your readers' eyes. Permalink | Leave a comment »
-
2moro Docs
-
Open-Source Tech Writing: the Time is Now
16 Oct 2009 | 9:11 amRecently, I started working with WordPress. For those unfamiliar with WP, it’s an open-source platform used for blogging, websites, and the like. Development and maintenance is completed by a world-wide community. There’s an incredible energy and community that is part of it. Last month, I attended a WordCamp event. Along with the information I obtained, I came away with one main thought: It’s time to apply this open-source model to technical writing. Why? The reason is simple. As I noted in an earlier post about industry trends, it’s impossible to keep up with all the changes… -
Must-Follow Trends for Tech Writers
1 Oct 2009 | 12:59 pmTech writers have always needed to keep up with current technologies. That is the case today more than ever. I’ve been in the field for over 20 years, starting back before online help, back when you copied manuals to put in binders, back when you wrapped up docs weeks before a release because you had to get the book off to the printer. That’s nothing like today. Changes are so massive, so fast, and coming from so many directions that it is impossible to keep up. Still, it’s important to try. For anything that applies to IT applies to tech writing. Writers must know something about… -
Must-Follow Twitter Feeds for Tech Writers
21 Sep 2009 | 9:08 amThe purpose of my blog is to provide tech writers with information about changes and how said changes may impact documentation. That is also the purpose of my Twitter feed. I gather up as much information as I can and pass it on. I’ve found some excellent feeds to follow related to the various topics of which tech writers need to be aware. Oftentimes, I include these in a #followfriday tweet. I’ve decided to list them here as well. Take a look. I’m sure you’ll find some feeds that are follow-worthy. They will save you hours and hours of time and provide interesting… -
HTML 5: What Tech Writers Need to Consider
14 Sep 2009 | 1:18 pmWow. I knew that there were many items to consider when writing documentation these days. However, there is much more than I realized. For example, today I started looking at HTML 5 more in-depth. As I read through the information on the W3C site, it became clear that big changes are in store that will affect technical writers. In HTML 5, a large number of elements will possibly be relegated to setup in CSS only. The major one I noticed initially is tables, as use of tables is obviously prevalent in docs. It appears that presentation elements will be handled through CSS. That includes… -
WordPress Rules! Goin’ to WordCamp …
28 Aug 2009 | 12:04 amOh boy. I feel like a kid at Christmas. I’ve signed up to go to WordCamp Seattle, taking place next month. That’s because, of course, WordPress is the coolest thing ever. I think that every tech writer needs to know it. How I ever lived without it before now I can’t say. I could easily see it being used for docs. Toss some words up on the blog. Collect comments for said entries; engage the users. Tag items and automatically sort them into categories for archiving. Add pages and subpages and more. Import a Twitter feed or two. Dig away; use the Search box to sift through the content.
