Know your audience

The first thing that needs to be taken into account and planned out for an effective technical writing assignment is to know your intended audience. Now while this may not be entirely possible, for various reasons, you still need to know your intended audience to the best of your ability. This is the biggest stumbling block to novices attempting to write a technical document (any kind) prior to receiving any formal training; they aim their writing either at their own personal "level" or aim it so low as to read like it was targeted at school children (over generalization).

For your writing to be most effective you need to create your document plan so it addresses the following audience needs:

Knowledge Level:

Does your audience have prior knowledge of the subject or is it new to them? What do they want to or need to know from the document?

Role:

Is your audience at management level, technical level or entry level? Are they decision makers who need to know certain things and in a certain order?

Interest:

Does your audience want to or need to know the document contents, or will they be more interested in only certain aspects of it?

Culture:

Is your audience's cultural background different to yours?

Personality:

Should you write in a strictly formal manner or more open and friendly?

As you can see from this list, you can't just go and throw together some technical jargon, legal speak and/or financial data and expect your audience to read or understand what you have written. It has to be tailored to the main demographic that will be reading it (or be expected to read it). Also, unless your intended audience is likely to know the terms in use, do not use abbreviations and/or acronyms without providing a clear deciphering of the term(s) when you first introduce them in the document. Even then, it is usually good practice to include the full term(s) somewhere in your document, as your audience may still need a "refresher".

The trickier part comes in when you are writing for a mixed audience and you are needing to write parts of the document for one audience and the rest for another audience. In this case you'll need to create multiple document plans - one for each expected audience. And don't worry too much about them reading the "other" sections of the document, they are very likely to skip over what they don't need to read, especially if it doesn't read easy for them.

Writing tools

There are a lot of different writing tools out there for technical writing, most of them are expensive commercial software titles. Fortunately there are also some Free Open Source Software (FOSS) titles available that are just as capable as the commercial options. To this end, I'd like to take a brief overview of the software I use (currently) as I start out in the world of technical writing. I will also separate out Mac and Windows versions as I am in a position to use both operating systems.

On another technical writing blog I was reading, the author had broken things down into the following four tool types:

1. Help Authoring Tools
2. Graphics Tools
3. Video Recording Tools
4. Page Layout Tools

And proceeded to list the most commonly used titles in each category. This is great for knowing what titles/tools you need to know but it is still a very general overview as there is no real standard. Different companies utilise different tools and it is hard (and expensive) to know all of them. Also, they did not cover any cheaper or free options that beginners, like me, can use to produce work while building justification for more expensive options. I have also only had the opportunity to explore tools from a couple of these categories - Graphics Tools and Page Layout Tools - as these are the areas I work in most at this time.

Here is the list of software tools I use personally (and some I have had the brief opportunity to test out); in no particular order:

• Photoshop (Mac & Windows)
• Scribus (Mac & Windows)
• Word (Mac & Windows)
• Monosnap (Mac)
• Notepad++ (Windows)
• TextWrangler (Mac)
• SnagIt (Chrome extension) (Mac & Windows)
• InDesign (Mac & Windows)
• TextEdit (Mac) and/or Notepad (Windows)

Now that I have listed out what I use, it would be more useful to you, the reader, to actually say a little about each tool - likes/dislikes, ease of use, functionality, cost (free/paid), etc.

Photoshop: What can I say about this graphics heavyweight? For most it is the industry standard for image editing. It is a commercial software title (read expensive) but the Creative Cloud subscription option does make it a lot more viable to those on a budget and is available for both Mac and Windows. It's only real competition in the FOSS arena is GIMP (Gnu Image Manipulation Program), which is a powerful editor in its own right but, to me at least, coming from Photoshop it is not as intuitive to use or as polished. I use Photoshop for all my image editing both personally and professionally.

Scribus: Many may not have heard about this FOSS title but you will likely know its commercial opposite, InDesign. Like InDesign, Scribus is a page layout tool and is availble on both Mac and Windows. After having a chance to compare the two, I would have to give the edge to InDesign for its slightly improved ease of use and overall polish. Not to say Scribus is lacking in features, it's not. This has quickly became one of my favourite tools for creating PDF documents, especially where images are included in heavily formatted technical guides. Once you place an item on the page, it stays put unless you choose to move it.

Word: While many might view Microsoft's Word as an industry standard, I personally have a strong dislike for it but am not able to escape from its clutches. It is so widely used that you need to know it, even if you choose to use an alternate; which unfortunately, there doesn't seem to be any true alternate out there without its own plusses/minuses. It is a commercial software title with different licensing levels (and costs) and is available for both Mac and Windows.

Monosnap: This is a free screenshot tool for the Mac that works really well for capturing and editing/annotating on-screen activity for help guides. I have used it recently for the creation of a software install guide and found it to be a very easy to use tool.

Notepad++: This is a free text editor for the Windows platform. Among it's many features is a very nice HTML editor that I have used quite a bit lately in creating my first HTML documents. If you're on the Windows platform and want a text editor and HTML editor this one is recommended.

TextWrangler: This is a free text editor for Mac, that I'm actually writing this content in. It is a free offshoot of BBEdit and shares many of its features. It is highly rated for Mac users wanting a text editor and HTML editor.

SnagIt (Chrome extension): This is a free extension to the Chrome browser to give advanced screen capture tools. It runs on Mac and Windows and seems a pretty robust tool, within limitations. It only captures what occurs in the browser window. This is where it looses out to Monosnap for me (on Mac) as I am not usually wanting to just capture the contents of my browser.

InDesign: This is a commercial tool from Adobe that does similar things to Scribus (listed above). I briefly explored the use of InDesign and liked the program, however, I changed my Adobe licensing and no longer had access to it. I make extensive use out of Scribus for all my page layout needs.

TextEdit and Notepad: These two tools are part of their respective operating systems and are useful, if basic, text editors. Many a website has been written in these two tools and as a low cost option (no additional cost over the OS) you can't go wrong with either one.

I would also like to add in one final tool that can be very useful, Google Docs. While I would not use it for creating anything more than a basic text file or similar, it does have great collaboration features; add to that the ability to login from any computer (regardless of OS) via a web browser and access all your files. It is definitely a useful tool to have in your toolbox.

New blog, new direction

You may have read posts I've made on my photography blog but this one is a little different. While there may be the occasional photo posted here, it is not my intention to turn this into another photography blog. This blog's direction and purpose is to allow me to explore more into the written word.

You could say that I am rather eclectic in my professional life as I have done many different things and even currently I wear multiple hats - I'm an IT Tech and Technical Writer who also has a sideline in photography. While I have been trying to launch my photography business I've been a "weekend warrior" and despite my efforts I've still not been able to make the leap from hobbyist to professional (still not making any income from it).

It’s not so much that I love photography as I am in a long term relationship with it; with all the trappings of such. There are times everything is wonderful and effortless; then there are the days where you barely can tolerate being around each other; and don’t forget the times you just want to pull your hair out, storm out the door and not look back. Normally though I’m somewhere in the middle of all that, although lately I have been more in the “self analysis” phase of wondering why I’m in this relationship with photography to begin with.

In fact, that’s most of what I’ve done lately - look at myself and think about my photography. It’s not that I’ve even been taking/making lots of photographs, I haven’t. I’m too much in my own head, trying to figure out the value of my photography and the direction I/it needs to go.

A new phase has started for me recently with my completing a technical writing class and undertaking this role at my place of employment. I am creating procedural guides and other documentation to build our knowledge base; something that has been sadly lacking there.

I find this very interesting as words are something I’ve not always had an easy time with. It’s not that I haven’t enjoyed reading (lots of) books, I’ve just never done a lot of writing - not creatively. I’m no great author, just your average person who can string a cohesive sentence together - and more importantly, get paid for it!

My wife seems to be of the impression that I have a talent for writing, although I think it is more for my style of writing rather than the content of what I write. But then again, I could be wrong as I tend to be too self critical, so I may be too close to the proverbial trees to see the forest.

Words are a strange thing. While they appear innocuous on the page, they really can affect us in positive and/or negative ways. They can make us ecstatic or cut us to our core. The power of words to wound is something that still takes me by surprise, especially as I have accidentally imparted unintentional tones to things I have written in the past.

Despite there being the old saying “sticks and stones may break my bones, but words can never harm me”, it is certainly flawed as words really can hurt, just in a different way.

Okay, back to the purpose of this blog, writing. As the name implies, there are times that my thoughts actually come together into something that might be worth writing down and might even be of interest to others. And as I want to keep my photography blog for photography related things, what better way than creating my own crazy corner of the internet where I can just write. Whether it is nonsensical or something more on the technical writing side of things, this blog is all about the written word.