Daniel Scocco is wrong. Not completely but fundamentally wrong enough that I need to call him out on his errors.

He points out Six Common Punctuation Errors that Bedevil Bloggers and, whilst all are grammatically correct, I think he is missing a point. Now on a technical level, as someone who writes for a living I, like most people,agree with him. I’m not posing what I’m about to say as an excuse not to write properly nor as any reason to ignore some basic rules of grammar but there is part of me that doesn’t think that the casual writier need to be as concerned with the laws of writing as a professional writer.

In other words, I know the law but I am not a policeman.

So let’s look at the six suggested rules:

1. Apostrophe for Plurals
OK, I can’t argue with this one at all. It is wrong people, stop doing it.

2. The Comma Splice
Whilst grammatically correct, it’s at this point I start to ponder what grammar means in terms of conversational text. A lot of bloggers aren’t trained writers, they have a basic grasp of grammar but little more, and it’s not something that concerns them. They are, typically, telling stories of a personal nature and mostly they adhere to a narrative take on writing.

Essentially they use punctuation to help phrase their sentences and see no reason not to use a comma as a “pause”, nor to use quotation marks for emphasis.

3. Quotation Marks for Emphasis
We’ve all seen the two-fingered air quotes used in film and I’m pretty sure we understand that they aren’t actually quoting anything, merely indicating a level of sarcasm. I will plead guilty to having done this on my personal blog where I tend to write freely.

4. Multiple Punctuation Marks
Technically correct. But there is a part of me that can only just muster enough energy to shrug this off, colour me apathetic. I don’t think either example is less-readable than the other.

5. Punctuation Outside the Quotation Marks
See Point 4. Ohhh and the main thing that annoys me about this kind of thing isn’t the grammatical inaccuracy, but the shapes the punctuation marks form.

6. The Missing Comma After Introductory Elements
I find this one surprising. As I mentioned in Point 2, most bloggers (or at least the ones I read) use a comma as a pause and the example given suggests that they’d use one there anyway.

And anyway, what does “Joe stopped on my house” mean?

I’ve commented on this kind of thing before, whilst I am a writer by trade I do think that, occasionally, we thrust our own perfections on others under the auspices of the common good. Everyone who speaks English should know these rules and adhere to them, we say. I’m sure other professions do the same, the joiner visiting my house will look at some of my attempts at D.I.Y. and shake his head in dismay. The key difference for those of us employed as writers is that our skillset is so widely used that the myriad of different abuses that assault our eyes on a daily basis make it all the harder to stomach.

As others have mentioned, the rules of grammar are interpretative and also depend on both where they were learned, and the location (and knowledge) of your audience. I totally agree with Daniel, if you are serious about your blogging then learning to write well is important. The real key is learning to write as well as your audience expects.

As a wise man once said, time flies like a banana. I may be paraphrasing (badly at that, sorry Groucho) so let’s skip on quickly. Brevity is the name of the game today for whilst I’m delighted that the company is allowing the development team to swan off for an afternoon of beer and ten-pin bowling, I am still losing several hours from my working week. With that in mind..

ISTC Conference 2007 writeup
File this one under “Ask and ye shall receive”. I’m a member of the ISTC but couldn’t make it to the conference, so I pinged their mailing list to ask if anyone who had attended would possibly write up their thoughts.

Many thanks to Mike Unwalla for taking the time to write up summaries and thoughts on the presentations he attended:

• Keynote address by Scott Abel
• Certification for Technical Authors
• Translation-oriented authoring—a prerequisite for efficient authoring
• Managing the lifecycle of your technical communication
• Leveraging DITA in a multilingual environment
• Writing justifications and comparative analyses
• Developing a communication-across-the-curriculum culture
• Staying agile
• Reasons to be cheerful—part 1
• CMS: how to avoid a content mess system
• Around the World in 80ms

Of key interest to me was the thoughts on working in an Agile development environment, with the suggestion of “Decoupling the publication of documentation from the delivery of the software” being something we are discussing at present. More on that later.

Scott Abel on Web 2.0
A shared set of slides from a presentation that aims to help us better understand how the semantic web (that’s the Web 2.0 bit) is impacting on technical communications, and how we can leverage some of the tools and ideas to our benefit.

I’ve touched on this myself a little, although I’m pretty sure the biggest impact is, and will remain, Google. This area is still (constantly) evolving so it’s worth keeping an eye on things.

Dependency Calculator

“In determining the risks involved in completing a publications project on time and on budget, some years ago my organization developed a simple assessment tool that we call a Dependencies Calculator.”

And oldie but a goodie. I developed something very similar at a previous company and after a few iterations it proved very valuable.

Requires Java.

Information R/evolution
Interesting little video that explores the continuing evolution of how we treat information. Simple and yet powerful and thought-provoking.

Sun Labs lightswitch

“I gave a talk at Sun Labs where I encountered a special light switch in one of their conference rooms. At first I thought it was some kind of silly “engineer” joke. But the light switch functions as stated for real.”

An excellent example of over documenting something rather than changing the design

Who am I?

“The biography is probably one of the most basic elements in a portfolio (what kind of website or blog doesn’t have an “about” page?) but can be one of the difficult. To this day, I still haven’t written one I’m 100% happy with. But hopefully with some different perspectives, it can be easier.”

I struggle with this kind of thing too, some good hints which should help improve things a little.

Writing for the Web
The website of the book that I’m now waiting on being delivered (gosh, what an ugly sentence).

PDF exploit in the wild
Sorry to end on a bum note, but something to note for those of you who, like me, distribute docs in PDF format. Don’t worry, it’s not as bad as things are made out (but what ever is?).

Make my living writing software documentation. There is, of course, much more to it than that, but that remains the bulk of the job. I also write as a hobby, both on this blog and on my other more personal blog. I also maintain a third website although that has been somewhat neglected recently (note to self: get the finger out!).

Suffice to say I write a lot.

In addition to that I have also adopted what is increasingly known as ‘web worker’ tendencies. As I work with, and on, computers it is simple enough to switch between different tasks, and the web is a key part of that working practise.

And the key part of that practise, for me, is Google Docs. The ability to import and export to Word, to easily maintain the content in relevant folders, and of course the ability to access and edit the content from any PC… well it’s almost a no-brainer.

But one thing that I’ve recently found useful, is the ability to share the documents, allowing others to view and edit them. Admittedly it was only between two people, but if you have a small team, or are working on a project that spans the globe (something that is increasingly common these days) then it’s worth having a look at Google Docs.

My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

I recall once being asked to breakdown all the skills required to be a Technical Writer, and then to provide a list of daily work tasks. The list of skills was to be used as part of a skills/training matrix, and the work tasks were to be mapped to a timesheet system.

At first I concentrated solely on the Technical Writers role, but even then you need to wear a number of hats; researcher, analyst, information architect, publisher, indexer, illustrator, proof-reader, editor… ohh and writer. All of those are unique job roles in some places yet, as a Technical Writer, you need to be able to successfully take on those roles to some degree. In most software companies a large part of the job is learning the new features, and as you have access to early builds, you are frequently also playing the part of ad-hoc tester. Admittedly you are usually only testing one scenario, and that scenario is the happy path that will be documented, but a bug is a bug and that means being able to identify one, discuss it with a tester or developer, or both, and why not log it as well?

If you are documenting an API or developer toolkit then, in those instances, you frequently don the cap of novice developer, asking the questions you expect them to ask, before switching caps to presume the role of an experienced developer and wondering if the information you are providing is too simple for them to use or if, perhaps, the structure of the information needs altered.

You need to be able to talk to developers and so you need to know a little about whichever code language they are working with, that way when they mention methods, you can ask whether they mean static or instance.

None of these skills/roles are the core part of a Technical Writers job, but simply additional strings to your bow. The more you know about everything, the more value you can add, so long as you don’t let that detract from your core responsibility, to provide documentation. However, the more you know about everything, the better that documentation will be and the higher your value will soar.

—

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).

My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

Working in the software industry, and particularly for a company that has embraced the XP development methodology, I have exposure to, and contact with, most of the other roles in the company. I talk to Marketing to understand to who, and where, we sell our software. I talk to Deployment to understand the real issues they experience when using our software (they are our customers). I talk to Training to make sure we are promoting the same message. I talk to Testing to make sure the bug that I have found IS a bug and should be logged. I talk to the New Feature development teams to understand what they are working on. I talk to the Core team to make sure I’m aware of the myriad of feature requests and bugs that they are fixing, and whether they impact the documentation. I talk to our Support team to understand the common issues being found. I talk to the Architects and product managers to make sure what we are doing fits with the strategy.

Throughout all of this I must have an understanding of both who I am talking to, and what concerns them on a daily basis. I need to know enough about how Marketing and Sales work, what languages the Development team use, and know the business reasons behind why a particular piece of functionality is being implemented, and throughout all of those discussions I have to remember my role, and consider how the information I’m receiving in the discussion may impact the user and, therefore, the documentation.

Frequently I find myself to be the cog that transfers a snippet of information from one area to another. A minor bug fix that relates directly to a new feature. Most times those links are known, but on occasion they are only discovered when one of my team has started to consider the documentation requirements in that area.

Talking to all of those people, these different professions has helped me understand my role, and re-enforced my belief that, whilst writing documentation remains the core part of my job, a large chunk of our value comes from making, and maintaining, those connections.

Perhaps Technical Communicators are the social web of the workplace?

—

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).

I’m a member of the Information Architecture Institute (IAI) but I’m still not really sure why.

I joined about a year ago, although I’d been following the website and reading articles in this area for some time before that. During that time I developed a sense that, at a fundamental level, there is a lot of crossover of knowledge and approach between practitioners of Information Architecture and those of us in the land of technical communications.

The IAI website states that:

As the information age rolls forward, our businesses, markets and societies are being transformed into adaptive, connected networks. The Internet of today only hints at the ubiquitous communication infrastructure of tomorrow. The construction of this brave new world requires a new kind of architecture, focused on digital structures of information and software rather than physical structures of bricks and mortar. As we spend more time working and playing in these shared information spaces, people will need and demand better search, navigation and collaboration systems.

Whilst a lot of the work of an IA is focussed on the web, the basic principles of good design hold true regardless of the medium. Given that many technical communicators provide online help which may, or may not, be delivered in a web format or via the web itself (as opposed to viewed locally in a web browser) those same principles can be used here. Even if we consider the production of information for print, the same considerations of information access and structure, personas and task analysis, require a level of understanding and design in which both IAs and Tech Writers specialise.

As an aside, this type of thing is one reason why you should hire a professional Technical Writer and not rely on other people in your organisation “filling the gap”. They may be able to write acceptable english, but information is next to useless if badly structured.

Looking further into the lair of an IA, we find many are now involved in what is commonly known as the “social web” (aka Web 2.0). With information being shared and promoted across many different areas, both geographical and social, the structure and usage of that information needs to be careful considered, and with more and more information sources moving from traditional outputs (print) to modern outputs (web), then the modern day technical communicator has, essentially, become what is now known as an Information Architect.

Strictly speaking it’s more another ‘hat’ for a Technical Communicator to wear but the idea is the same. As well as writing, design, illustrating, and doing everything else that is involved with creating technical documentation, now may need to consider an additional mode of usage, one which has grown rapidly in the past couple of years.

The more I learn about Information Architecture, the more parallels I find. Designing information structures, leveraging an ever increasing set of tools, is fast becoming part and parcel of our jobs (well, ok, MY job at least). Add in the fact that we are, frequently, the people populating those structures then it’s easy to see that there are many lessons we can learn from those in IA.

Related Information:

• IAI website
• Boxes and Arrows

Another week, another quick set of links. I really should start using one of these new fangled “social bookmarking” sites for this, shouldn’t I. Problem is I already have a del.icio.us account for personal use, and I like being able to add some thoughts about the links but it limits that slightly.

In saying that, it does mean I give each link proper consideration, rather than just bookmarking them in passing. With that in mind, I thought I’d change the format of this post a little and offer a little more thought on each. Hopefully the links remain interesting and useful to others.

In a (short) post entitled Identical vs derivative reuse Ann Rockley suggests that

“one thing is certain, that companies can reuse more content then they think”

If you are currently investigating reuse opportunities within your company then you should find this interesting. Understanding the potential is a key part to forming your single sourcing business case, and if nothing else it offers some handy reminders of places to look.

Anne Zelenka wonders why companies are moving away from cubicles to open plan spaces to aid communication, and proffers some suggestions in her post titled Mold the virtual space, not the office space

“Lots of web workers are traditional employees and go to an office every day. But they can still take advantage of the web to reach out inside and outside their company.”

In my personal experience, open plan offices are a boon to the technical author in many ways. Physically locating a technical author with the development team that they are working with ensures that they catch all those snippets of information that typically disappear into the ether.

However, the downside is the constant distractions and background noise. As such I tend to spend a few days a month working at home, setting work aside for those days as I know I can tackle larger chunks of work with little to no distraction or interruption.

The first of two links to the ever thought provoking Ann Gentle. Her article The “Quick Web” for Technical Documentation, which discusses using wikis for technical documentation. is available as a downloadable PDF. The article was recently published in the STC magazine Intercom and others sage advice (as ever).

Keeping on the wiki theme, I came across a summary report from an MBA student that covers Managing Wikis in Business:

“indicates that wikis have provided platforms for collaborative and emergent behaviour, enabling people to work/communicate more efficiently and effectively, learn from past experience and share knowledge/ideas in organisational contexts that are not averse to collaboration”

I’ve not read the full report yet, but looks very interesting.

Are you involved with the UI design of your application? Joshua Porter makes the case that you should be as interfaces need editors:

Editing is mostly about clarity and making the interface concise. It’s a lot of copy-writing, and only a little rounding corners.

With a task view of how an application is used, there is an easy ‘in’ to this area for most technical writers.

Sticking with UI design, if you are interested in this area have a look at these articles from Apple Insider. Whilst they are focussed on new elements of the “soon to be released” Apple OS, they start back in the days of early GUI. Fascinating stuff, or maybe just a nice bit of nostalgia. The articles cover the new Dock, Spaces, and Finder.

Finally a doozy of a post from Ann Gentle. It’s the type of thing that makes my head spin and sort of, maybe, ties in with my own thoughts on structured authoring within an Agile development environment. Single sourcing documentation, following a structure such as DITA, matches the fast pace of Agile development, to improve collaboration and make the sharing of discrete chunks of information more open a Wiki makes sense. So, in my mind there is a match, or at the very least a correlation between structured authoring (DITA) and Wikis. However Ann, in discussion with Chris Almond and Don Day, comes to get:

“a sense that there are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture. Also, the types of information that these authors are trying to capture are opposed in some senses.”

It’s a fascinating post and has certainly got “ideas popping and synapses firing” in my brain. Are structured authoring and wiki opposing forces? is a question which is going to keep me occupied for a while.

That’s all for now. Next week I’m going to try and NOT feature a post (or two) from Ann Gentle but we do seem to share a lot of similar ideas. Don’t worry, I’ll “spread the love” as they say.

Right I’ve got a presentation on Using Wikis for Collaboration to finish. Pass the caffeine please.