"Managing Your Documentation Projects" by JoAnn Hackos -- an overview

Everyone in the office where Tim and I work is issued a copy of JoAnn Hackos's Managing Your Documentation Projects. In this blog post, I'll provide some general remarks about this often-issued, not-so-often-read book.

JoAnn Hackos's Managing Your Documentation Projects (hereafter, MYDP) discusses technical writing from a managerial, strategic perspective, with emphasis on implementing a process for documentation development. MYDP provides a 5-level model for assessing the maturity of your documentation team.

It is important to say what MYDP is not. MYDP is not a manual for teaching you how

Archived Seminar Review: Strategies for the Social Web for Documentation.

Introduction:

The STC website has about 90 archived seminars, webinars, and presentations. Access to all this material is included in your dues. They are mostly over an hour long, and cover a range of topics. As a public service to STC members, I decided to watch and review them all. One at a time.

Review Number 2: Strategies for the Social Web for Documentation.

In this presentation, Anne Gentle (author of Conversation and Community: The Social Web for Documentation) explored possible intersections between technical communication and social media, or the social web as she calls it. Anne explained how she thinks technical documentation could change and improve through more direct user interaction. She also tried to put to rest the idea that user generated content will one day put us all out of a job.

Don't be mean to non-writers.

I've gotten better at writing since I started being a technical writer. And sometimes my pride in myself verges on smugness.

I came across this blog post, that helped me remember how important it is to be humble, and stay off high horses. This line in particular hit me:

"The idea that there is only one right way of doing English – and everyone else is doing it wrong – is inherently flawed. And by “flawed” I mean illogical, elitist and even oppressive"

The point is, worry about your own writing, and learning more every day. It's one thing to help people learn from a place of respect, and another thing to cut them down for not being as awesome as you are.

Tips for Queenslanders dealing with hail in their driveways

This afternoon saw pretty impressive storms in and around Brisbane, leaving some people with hail in their driveways and on their lawns.

I grew up shovelling my driveway in the wintertime. For the readers who are at a loss on how to get started, I found this piece of technical communication that should help.

One more day for submissions!

There is one more day to submit your entries for the STC Australia Chapter's Technical Communications competition. Don't procrastinate any longer!

Competition details are here. Entry form is here. Payment information is here.

Good luck!

Passive voice bookend.

I started my holiday with an image of some bad passive voice.
This is a less bad example, but I wonder why they didn't tell customers to "Purchase tickets at the Fire-Fly counter"?

New payment methods available for competition entries.

I didn't want this to get lost in the previous post.

We're now accepting online credit card payments for competition entries using TryBooking's secure payment service. You can pay online at http://www.trybooking.com/CDCC and http://www.trybooking.com/37234.

Additionally, you can make a bank transfer to the STC Australia Chapter's bank account. For the bank account details, email the treasurer at treasurer@stc-aus.org.au.

Good luck!

Deadline for STC Australia Chapter Technical Communication Competition 2012 submissions extended!

Goodness gracious, saints alive!

You read that right, you now have some precious extra days to make a submission to the STC Australia Chapter's Technical Communication Competition. Entries are now being accepted until Friday 16 November 2012

So finish touching up that manual, diagram, or insanely awesome report, and get it submitted!

Here is a quick read for more information. Competition details are here. Entry form is here.

Good luck!

List of Books on Tech Writing

Here is the beginning of our list of books about technical writing and books that double as useful tools for technical writers:

• Hackos, JoAnn, Managing Your Documentation Projects (New York: John Wiley and Sons, Inc., 1994)
• DeRespinis, Francis et al., The IBM Style Guide (Upper Saddle River, NJ: IBM Press Books, 2012)
• Rosenberg, Barry J., Spring into Technical Writing (Upper Saddle River, NJ: Addison-Wesley, 2005)
• The Chicago Manual of Style (Chicago: The University of Chicago Press, 2010)
• Brooks, Fred, The Mythical Man-Month: Essays on Software Engineering (Anniversary Edition) (Addison Wesley, 1995)
• Kernighan, Brian and Ritchie, Dennis, The C Programming Language (ANSI C) (Prentice Hall, 1988)

Please comment and tell us which books have been important to you in your role as a technical writer.

Note: Tim Hildred is on holiday until mid-November. Zac Dover is blogging in his absence. 

The Case for Writing about Tech Writing

Technical writing, being a fairly recently-emergent discipline, is still in the process of developing a set of standards and protocols. In this, it distinguishes itself from well-defined disciplines such as mathematics, empirical science, deductive logic, and (even) cooking.

Despite the field's incipient nature, technical writing has been described in a number of books that are worth study and discussion.

I have a better warning.

I would have said:
"Your baggage might be screened after you check it in."

If you can't sell your employer on a standing desk...

You should consider investing $20-30 dollars in your own health.

I'm almost 29 years old. I'm getting tubby, and I have back pain. I think that part of the problem is that I sit for at least 8 hours a day, and sitting is bad for my health.

I was talking with one of the facilities staff in my office today . She said that without getting a doctor's note saying that I need a standing desk, I'm going to have a hard time convincing the company to pay for one.

For between $20 and $30, you can build your own.  I'll build one, and see if the company I work for can't be guilted in to reimbursing me.

And yes, I'm hopping on the standing desk bandwagon. At least I don't have a fixie.

Would your employer spring for a standing desk? Would you?

Google Drive instead of Microsoft Word?

As a long time Linux user, I'm all for ditching the Microsoft Office suite. Its not that its "bad", its just not free.

Here is an article about some of the advantages a teacher saw in swapping Google Drive (formerly Google Docs) for Microsoft Word. Google drive has its own costs associated with it, namely the giving of data to Google (presumably for "not-evil" purposes)

The big advantages the teacher saw were easier collaboration, built-in version control, and the leaving behind of comparability issues.

I know that some people write about stuff they just plain couldn't give to Google. What about you? Could you make the switch?

Don't blog about writing.

I've been looking around for blogs to add to the STC Australia Chapter blog roll as part of my strategy for growing our readership[1]. Today, I came across the blog of a social media strategist named Kristen Lamb who specializes in helping writers make money by blogging.

Kristen Lamb wrote a blog post explaining why writers shouldn't write about writing. Her advice to word-slingers is to blog about your interests, and grow your readership by finding people who relate to you personally. Writing about writing limits your audience, and unless you are blogging to establish your own expertise on the subject of writing, you are missing out on a larger group of people who prefer reading to writing.

I have a sneaking suspicion that most technical writers aren't strictly technical writers. Almost all of the technical writers I know and work with are secretly poets, screenwriters, sci-fi fantasy authors; creative types who write procedures so that they and their families can eat.

Do you have a blog, about writing or otherwise? If you introduce yourself and leave  a blurb about your blog URL in the comments, I'll add it to the blog roll.

And maybe you can add us to your blog roll.

[1]Our readership, I suspect, is currently committee members. I have a dream that one day, people I can't even imagine might read this post.

Tech Tools: Prezi and SpicyNodes

This migration from page to blog post represents the first in a series of tools related posts. This is recycled content, but we had to start somewhere.

STC Committee member Bea Amaya collected this information. 

Prezi

"Prezi is a web-based presentation application and storytelling tool that uses a single canvas instead of traditional slides. Text, images, videos and other presentation objects are placed on the infinite canvas and grouped together in frames. The canvas allows users to create non-linear presentations, where users can zoom in and out of a visual map. A path through different objects and frames can be defined, representing the order of the information to be presented. The presentation can be developed in a browser window, then downloaded so that an Internet connection is not needed when showing the presentation.   Prezi uses the freemium model. Customers who use the free Prezi Public license must publish their work on the Prezi site. Customers who pay for a Prezi Enjoy or Prezi Pro license can create and share private Prezis. Prezi also offers a special education license for students and educators." Wikipedia

SpicyNodes

"SpicyNodes is a way to visualize online information that mimics that way that people look for things in the real world. Bits of information — such as text, links, photos, and other media — are placed into 'nodes,' which are then linked together in an appealing interface that invites exploration. SpicyNodes can be used for everything from mind maps and content portals to organizational charts and lesson plans." About SpicyNodes. Feel free to visit one of mine (one I created, but never finished, for my Feminist Theory class) as an example. SpicyNodes is a very cool mind mapping tool that is also free.

STC Australia Chapter Social Media Launch

Though I mentioned all of this in a previous, unrelated post, I think its worth doing an official, "we-do-social-media-now" post.

Like us on Facebook!

Follow us on Twitter!

Do whatever the equivalent of those things is called on Google+!

I'm hoping these mediums can become a little more participatory than this blog. I know there are Australian STC people out there. Come talk to us!

Nice looking blog, something to aspire to.

I found the Australian Science Communicators website/blog. It looks really sharp.

I hope that one day, the STC Australia Chapter blog/website looks this good.

In other news, I just used Twitterfeed to make blog posts here result in status updates on the STC Australia Chapter Facebook Page (go on, Like it, you know you want to), and as tweets on the STC Australia Chapter twitter feed. I also added Google+ integration so that each post here also shows up on the STC Australia Chapter Google+ page. 

You'd think a social media bonanza like that would merit a separate post. I agree... later.

Annual STC Australia Competition accepting submissions!

Every year the STC Australia Chapter runs a technical writing competition to find the best of breed technical communication Australia has to offer.

Information about this contest was sent to the email accounts of STC members. However, the contest is open to all, and the entry form is long, so I thought I'd give a summary for those deciding if this competition is for them.

Find out more after the jump. 

STC running events across the globe... which no longer includes Australia

Our parent organization is in the midst of conference season. All around the globe, technical communicators are gathering to talk shop, drink culturally appropriate beverages, and further our craft.

The September issue if Intercom (a bit late, I know) has a map of the world, with event locations marked on it. If an alien race were plotting an invasion based on the map in Intercom magazine, technical communicators in Australia might squeak by un-conquered.

Australia, according to the STC world map, doesn't exist!

Archived Seminar Review: Process Re-engineering for Topic Based Authoring

Introduction:

The STC website has about 90 archived seminars, webinars, and presentations. Access to all this material is included in your dues. They are mostly over an hour, and cover a range of topics. As a public service to STC members, I decided to watch and review them all. One at a time.

Review Number 1: Process Re-engineering for Topic Based Authoring.

This presentation focused on the difference between how an organization produces topics and how an organization produces books. The speaker, Rob Hanna, is engaging. His slides help you follow along with what he is saying, and probably help him remember what he is saying. It is a bit boring to look at slides and hear someone talk, without seeing their body language, but that's what you get learning on the internets in 2012.

Eye Guide Updates

Last year our chapter purchased a device called "Eye Guide", designed to be used as an eye-tracking tool in order to assist designers and developers analyse user interactions with computers and other devices and improve usability. Although I don't believe anyone has used the tool yet I would really like to encourage each of you to think of an application and try it out. It does not take long to figure out and puts some cool technology in our hands. I'd love to see someone from our chapter use it, then report on it here.

As a follow up, I thought I would share a video about how the developers of this device continue to move forward. I have to put in a disclaimer here, however...the inventor, the man in the video, is the chairman of my dissertation committee and works at the university I attend. I'm just so impressed with the ways they keep moving forward with this technology finding more innovative ways to use it. Check out the video below if you get a few minutes free.

What would you dedicate 4 hours a workday to?

I read lifehacker.com.au. I found this article there. Research is discussed with an upshot of "dedicate 4 hours per day to 1 thing".

Do most technical writers write for 4 hours a day? Solidly? I'm not sure I do.

I think that I do more research and maintenance than pure content generation. Is that standard?

Its probably worth trying the 4 hours of dedicated work on a specific priority. I would never have guessed that as a writer, one of my main priorities would be content shepherding.

But between correspondence about content, other research on background for the content, and the testing of content, I must spend 4-6 hours of every day on what is essentially writing preparation.

I guess the difference between my work habits and the ideal presented in this article is the level of focus. I do all of the above interspersed with answering colleagues questions, attending meetings, and meeting non-writing obligations.

Another difference between me and the mythical worker the researchers present as worth emulating is the 6:30am start time. 

BBC teaches English? Makes sense, though.

This wasn't for documentation, but a letter. Sentence ending on "though".

The line I wasn't sure about:
"That book is probably due for a pretty serious overhaul, though."

Comma? No comma?

According to the BBC, comma!

Project management resources, anyone?

One of the ironies of the information age is the extent to which our access to information makes it clear how little we know.

And by we, I mean me.

I think as I post more here, it will become clear how important "Open" is to me. Open Culture offers free ebooks, text books, and audio books. Free as in, we are a free people, free to learn and better ourselves.

One of the resources linked there is Project Management: from Simple to Complex.
Will it make you a better person? No. It might even make you a more effective evil person. 

But it might also help you plan your documentation efforts. 

On Outlining.

I found an article on outlining[1] that promises I will write faster if I outline more completely.

The author thinks of her outlines as a series of questions that she will answer in her article.

I'm used to outlining when I already have the answers I need.

The idea is that if these two things are combined, you'll have a complete outline.

I could see this being especially helpful when planning for an SME (subject matter expert) interview. If your outline for the interview contained both the questions you wanted answered, and some example answers to goad your SME into correcting you, you'd probably get really good results.

Planning your documentation in terms of the questions your users might have is also a good idea.

The article makes good use of whitespace.

[1] http://www.onespoonatatime.com/how-to-save-tons-of-writing-time-by-using-a-complete-outline

Serial comma

On the same vein as Tim's post, the serial comma is something of a problem. I have been taught (in the past and fairly recently), that the serial comma comes into effect only when more than two options are described. That is, if I write "Select a or b" or "Select a and b" the comma is not required.

However, the comma is required when either more than two options are available, or one of the options has two options. That is, you can have "Select a, b, or c" or "Select a or b, c, or d" or "Select a, b or c, and d" and all the other possible variations.

But now I am being told that I must have a comma at all times to ensure that there is no confusion. So, I find myself continously having to correct what I write to introduce that extra comma "You can select a, or b".

Personally, I do not agree with this option. Thoughts?

That or which?

That or which?

I'm working on fixing up some documentation for a release. I came across this:

"Before you begin, the export domain must be attached to the data center which contains the virtual machine to be exported."

I thought "which" looked awkward, but wanted to double check. I found this resource:

Using which and that correctly

Which says:
"Use which (surrounded by commas) if a group of words adds information. Use that if it limits the set of things you're talking about"

Seems simple enough. But not so fast.

My colleague informs me that this approach to "that and which" was popularized by Strunk and White in the 1920's. Before then, the words weren't used consistently as restrictive(that) and non-restrictive(which) clauses.

He didn't have a counter example, and I am happy to accept a simplified approach on this issue. In my edit, I substituted "that" for "which", and went to get a soda.

If someone reads this, and thinks of an example where this guideline doesn't work, please comment.

Did You Know: "Free Archived Seminars"

When I was poking around in the STC.org website this week I stumbled across an area that I know about, but often forget about--the "Free Archived Seminars". This is an area of the site that provides some really decent high-quality content seminars. This week I randomly selected a seminar to view called "Collaborating Around the World" and was surprised to discover that the presenter is an Australian living in the USA. Her presentation was really delightful and I found her content to be on-target and insightful. If you haven't checked out this section of the STC website I would suggest you take a few minutes and give it a try. Here are some of the topics covered just in this single presentation:

Mincom

Our team environment

Dealing with time zones

Dealing with cultures

Australian and US cultural differences

Creating a team culture

etc.

I can't wait to find the time to see what other content is available for me to learn from in this section of the STC.org website.

STC Presents :: Create Meaningful Online Experiences

The descriptive blurb says, "What makes one website memorable and another wholly forgettable? What drives you to return to a site repeatedly? The answers are often surprising and decidedly low-tech. This webinar will examine the concepts and intentions driving several compelling online experiences with a focus on uncovering ideas worth putting to work at your organization. You'll gain an understanding of elements that create meaning, an awareness of existing ideas and approaches worth stealing, and a knowledge of success measurement to apply to your own efforts." 6:00-7:00 AM Friday, 17 August, GMT+10.

This seminar is available to STC members for $59 (USD) so if you're interested, be sure and visit the STC Website to register.

Although I know nothing about this presenter, Patrick DiMichele, the list of "Honors and Awards" on his LinkedIn page makes me think he might have something valuable to share. If you decide to sit in on this session we hope you'll give us a report on it in one of our later Chapter meetings!