Posts Tagged ‘Tools’

Increase your productivity with these applications

Posted in Tools on February 24th, 2011 by Jenny – 3 Comments

Touch New Zealand / ChristchurchWhen you work as a contract technical writer, you can maximize your productivity by choosing the tools that work best for you. These tools can vary widely depending on who your clients are and the type of work you’re doing. And they change as technologies improve. Today I thought I’d share five applications I currently use every day.

1. Outlook 2010

Remember the days when you had a single email address? Maybe you’re lucky enough that you still do, but most of us now have five or more email addresses. For security and convenience, some of my clients prefer me to use a company email address on an exchange server. What this used to mean was that I had to have a VPN connection into the company, and an Outlook profile configured to access the exchange server. Or use Outlook Web Access, which is great if you’re out of the office for a short time, but awful if you have to use it regularly. If you had more than one exchange account, you had to have an Outlook profile for each account.

With Outlook 2010, this is no longer true. Now, you can have several exchange accounts and other pop accounts visible from a single profile. Each exchange account has its own Inbox, Calendar, and Task List, but you can do clever things like view calendars one on top of the other, so that you can see a whole day or week of meetings at a glance. This works surprisingly well, although you have to be careful to add tasks and appointments to the correct list or calendar.

TIP: Select “Use Cached Exchange Mode” on the Server Settings page for exchange accounts. Initially I didn’t have this check box selected, and so because Outlook assumes the exchange account is your primary account, when the exchange server was down for maintenance, I couldn’t open Outlook, because it couldn’t connect to the server. Once I’d selected Cached Exchange Mode, Outlook ignored the fact that it couldn’t connect to the server, and simply showed me the cached view of my mailbox.

2. Dropbox

Often I work using a Remote Desktop Connection. The application I’m writing documentation for is installed on a machine in client’s office, and other software that I use, such as RoboHelp, is also on that machine. This makes it really easy to take screenshots, cut and paste text from one file to another, and use SourceSafe with a database on the network, all without needing a VPN connection. But at times the connection can be slow, and if I’m working on a Word document, for example, it’s easier to email it to myself and edit it on my own computer, particularly for documents that require lots of reformatting. For a few months that’s what I’d do – email documents back and forth. And then I discovered Dropbox.

Dropbox lets you set up a synced folder. Install it on your remote and local computers, and then simply drag and drop files into the Dropbox folder. Then you can work on the files from either computer. For example, when I’m working on release notes, I put the Word file in my Dropbox folder, open it on my local computer to do all the formatting, save and close the file, then open it on the remote computer to add the necessary screenshots. You can also set up shared folders with other Dropbox users. It’s so simple to use, I can’t imagine going back to emailing documents to myself.

3. Skype

I know I’ve talked about using Skype before, as a way of staying in touch with people you work with remotely. But did you know you can use it as a simple desktop sharing application? Technical writers explain tasks simply and clearly, which means we’re often asked to help with training or problem solving for the applications we’re familiar with. For example, I’m the go-to person for installing the SourceSafe client, for figuring out why CHM help files won’t display over the network, and for fixing Word documents so that markup and comments don’t appear in the printed version.

Using the Share Your Screen feature of Skype, I can now see the person’s desktop and talk them through the issue, seeing exactly what they’re seeing and clicking on.

To share your desktop, make a Skype call to the person you want to share your desktop with. Once you’re on the call, go to the Call menu, and select Share Your Screen. The person you have called should maximize their Skype window to see your desktop at full size. There is no way currently to give someone else control of your mouse, but for simple desktop sharing, this is a quick and easy solution.

4. Keepass

I first learned about Keepass from the book titled Upgrade Your Life (this book has tons of great ideas for better organizing your electronic life). Keepass is a simple database for storing your usernames and passwords. As a technical writer I have hundreds of user credentials for things like my network login, applications, and product forums. I used to keep these written in a notebook, but then when I was looking for a password, I had to remember which notebook I’d written it in.

With Keepass, I now have all my passwords in one place. I don’t have to remember them, and I can easily find them, even if I only use a password once a year.

If you don’t like the idea of keeping your passwords in a database, another suggestion is to use an Address book, indexed with letters. Keep your Skype username and password under S for Skype, or your Madcap User Forum information under M for Madcap. But really, try Keepass!

5. Notepad++

I use Notepad++ for editing HTML files. For one of my clients, I manage a static web page, adding links to technical documents to the page once or twice a month. For work like this, there’s no need for a full-featured HTML editor. Notepad++ displays the HTML with colored tags, making it easy to see where I need to add my lines of code. Simple, but effective.

How about you? Do you use any of these tools? Which other tools do you use to increase your productivity?

Photo via Flickr user Shawn Huang

Sympathies to all the people in Christchurch NZ affected by the earthquake this week.


Confluence wiki – first impressions

Posted in Confluence and JIRA, Tools on February 16th, 2011 by Jenny – 5 Comments

Bird of Paradise FlowerAs a technical writer, I love learning new tools. In this case, I’m implementing a pilot project using a Confluence wiki.

Until now, all our technical documents have been Word and CHM help files. And we’ve delivered these to our customers as links on a static web page.

This method made it easy for lots of folks to contribute to the documentation, but it also had a number of downsides. These were the things I wanted to address if we changed to a different system:

  • Global searching across all documents
  • Enterprise-level security
  • Automatic update notifications or feeds
  • A more efficient process

After a lot of research, Confluence seemed like the answer.

Yesterday I downloaded the latest evaluation version (Confluence 3.4). Our IT group is installing it on a server, but in the meantime I’ve installed it on my desktop, using the simplest settings, to get it up and running as quickly as possible. Once it was installed, I wanted to dive in. (Why is it that technical writers are so reluctant to read the tutorials first?) Anyway, without further ado, here are my first impressions:

1. Create a new space.

Easy! On the Dashboard, click Add Space. Give your space a name and a keyword, and click OK.

2. Change the layout.

Click Browse, Space Admin, then Themes. This can be as simple or as complicated as you want to make it. I chose to use the built-in Documentation theme, because I like to have the tree navigation on the left side of the screen. But eventually I’ll probably want to use the Adaptavist Theme Builder for a customized theme that matches the look and feel of the corporate website.

3. Add pages.

In your new space, click Add, and then Page. Give your page a unique name, and click Save. The unique name of the page is critical, and I’ll come back to this later.

4. Add content.

On your new page, click Edit. By default, you are on the Rich Text tab. You can start typing, add links and images, or you can click Insert to add macros to your page. Macros include things like a column layout or a mini table of contents. If you’re like me and you want to see the code view, click on the Wiki Markup tab. If you know which macros you want to include, it can be quicker to just type them here rather than going through the menu on the Rich Text tab.

5. Add attachments.

I figured the fastest way to add content to my new wiki would be by adding links to existing Word documents. That seemed straightforward.

On your new page, type the name of the file you want to link to (or whatever text makes sense), select it, click the Link icon, click Attachments, then browse for your file.

But I have so many files to add! There must be a faster way to add attachments. And sure enough there is. With the page not in Edit mode, click Tools, Attachments. With Google Gears installed, you can drag and drop files onto the page.

Everything worked great, until one file gave me an error – it was too large! After some searching I discovered there is a way to increase the size of acceptable attachments, but keep this in mind when you start out. The default setting is 5mb.

6. Import a Word file.

My initial plan is to replicate our existing static web page, but in the long term, I’d like the content to be written on the wiki. This makes it easier to update and much more efficient. But it means getting the content from the Word documents into wiki format. I decided to try out the built-in Word document importer (Tools, Import Word Document). Initially I chose not to split the document, so the entire thing was on a single wiki page. Once I added a Pagetree macro, to create a mini table of contents at the top of the page, this was acceptable. But I thought it would be better if I split the document into sections.

Remember what I said earlier about page names being unique? Well in our Release Notes, we structure the document by product modules, and each module contains sections for Enhancements and Corrections. In a wiki, depending on how I split the document, all these headings that are the same, have to have unique file names. For now, I’ve decided to split the document at the module level, but what this highlights for me, is that I can’t just import our current hierarchy into the wiki. We’ll need to consider our structure before moving forward.

The next step is to meet with the stakeholders to talk about exactly what we want to accomplish with the pilot project. Whichever structure we choose, we’ll have global searching – check that off the list! Tomorrow I’ll investigate the security and feeds to see how they work.

Are you using Confluence or another wiki for documentation for an enterprise application? I’d love to hear your experiences and suggestions in the comments.

If you liked this post, consider subscribing to my RSS feed. Or have posts delivered via email. Thanks for visiting!

Photo via Flickr user Jason Pratt


Must-have tools for new technical writers

Posted in For new technical writers on January 19th, 2011 by Jenny – Be the first to comment

Chocolate ToolsThe one question I’m always asked by people who want to become technical writers is “What tools do I need to know?”

Usually I say “It depends…” but I’ve come to realize that one tool alone is the most useful for new technical writers to learn.

Microsoft Word.

I can hear the howls of protest, but just wait a minute while I explain my reasoning.

Everyone thinks they can use Word, but are they using it like a technical writer? No. You can learn to use features in Word that will help you learn other technical writing tools. Grab a pen, write down these things, and then practice using them.

1. Styles.

I don’t mean applying bold or underline by selecting text and clicking the icon in the tool bar. I mean setting up paragraph and character styles, and then applying them consistently throughout your document. Take your resume, for example. Have you used heading styles for headings, bullet or number styles for lists, body text styles for paragraphs? The first thing I look at when I’m reviewing technical writer resumes is styles. If I see inline formatting, I assume the person doesn’t have much experience, despite what their resume says. Sounds harsh, but it’s true. Your resume should showcase your technical writing skills. And knowing how to apply styles is a vital skill that you can easily port to other technical writing tools. Learn to use styles!

2. Generate a table of contents.

Once you’ve learned to use styles, especially heading styles, you can generate a table of contents. When I say generate, I mean that Word can cleverly find all your headings and create a table of contents for you. But don’t edit the generated table of contents manually, because the next time someone presses F9 in your document, it’ll be updated automatically, and you’ll lose your manual changes. If you need to change something, go back to the source heading and change it there.

3. Keep the text inline, don’t use floating text boxes.

This one is important if your document will be translated or localized. Companies often send their documents out to big localization houses, which suck your text out of the document, translate it, then plop it back in. If you use floating text boxes, the text can end up lost or misplaced. If you need your text to sit outside the margin, create a custom style for the text. If you know this, you’ll keep the localization manager happy by keeping localization costs down.

4. Review the document properties.

Documents generally contain metadata such as who created them and when they were last edited. As a technical writer, you don’t want to send out a document that contains an incorrect company name or other information that could be embarrassing. Always check the document properties and update them with the approved details. Some companies prefer documents not to include your personal name, but rather to be written by the “Technical Documentation Department” or something similar.

If you know how to do these four things in Word, you’ll already be ahead of the other writers who think technical writing is just about the writing – it’s not! And if you’re still worried about learning other technical writing tools, visit the company websites. Often they have free trials, so you can download the software to your computer at home, and practice making a help system out of your resume or the novel you’ve got hiding under the bed.

Here are a few to get you started:

Flare, RoboHelp, FrameMaker, InDesign

Photo via Flickr user JanneM