Conference season is underway, with DocTrain and AODC recently finishing. As such there is a lot of great and interesting blog posts out there, some are catchup style so if, like me, you didn’t attend you can still get some nuggets of information from them. But the type I prefer are the ones which collate the various ideas and pull them together.

So, with that in mind, if you only read one of the posts linked below, make it the first one.

DocTrain Conference thoughts
Tom chats to Noz Urbina from Mekon and starts to pull together some of the varied threads I’ve covered here into a vision of the future which, in my opinion, makes sense. It’s great to see this kind of thing being discussed and it’s the step beyond where I’d gotten with my thinking. Well worth a read.

Some thoughts on writing better error messages
Real-world tales of woe shed some light.

This lack of coordination between error reporting and error origin often leads to incorrect human reasoning about root causes. One simple help to sysadmins (and other users) would be to report errors in context.

Separating content, structure, format and behaviour
One from a session of AODC which helps properly define how and why we should be separating out the various components of information production.

What we’re aiming for:
* Maintainability — you can change one of the above four components without breaking the others.
* Re-usability — you can re-use the same bit of JavaScript, for example, in other documents.
* Separation of skill sets — different people can work on the component they know best and enjoy most.
* Simplified updating of content — content is likely to be the component you update most often.

Designing for the Social Web: The Usage Lifecycle
Pertinent to anyone working with an application that has any form of social web (web 2.0, community interaction, pick a term) features, or for those of us trying to build an online community around their product

The lifecycle is particularly relevant to web-based software because the product is inextricable from the service. The product is the service. If a person has a question about what your software does, for example, you can literally build that answer into the software itself.

Wiki on a Stick
And finally, a downloadable, zero install, personal Wiki. May be useful if you want an example of how Wikis work. Extra handy for maintaining your own To Do lists or as a way to centralise your notes (or both).

That’s all for now.

I took a few days holiday last week (if you get the chance, go visit Budapest, it’s lovely) so here’s a little bit of catchup from the RSS feeds I monitor. You can download the list over on the right there.

How Corporate RSS Supports Collaboration and Innovation
Dennis McDonald pulls together some good arguments around introducing Web 2.0 ideas to your company, noting that a lot of business cases rely on raw numbers and that, in the case of social networking tools, there is:

… a disadvantage of taking a “beancounter” approach to implementing social media within an organization. While you might be able to quantify the time, effort, and technology associated with impacted processes, you can’t necessarily predict when and where the benefits (such as innovations or new ides) will occur.

Bye Bye GoLive!
Adobe finally realise what most web developers already knew, GoLive can’t compete with DreamWeaver (also now owned by Adobe). However, it’s not all bad news if you are a GoLive user:

the company will continue to support GoLive users with online tutorials and migration assistance created by usage experts. The company has also collaborated with online training service Lynda.com to provide tutorials for GoLive users.

And one more thing
The Hoefler & Frere-Jones blog continues to provide some fascinating information for typographists (?) and writers alike. This time they take a look at the many forms of the ampersand.

As for the word “ampersand,” folk etymologies abound. The likeliest account, offered by the OED, is explained by early alphabet primers in which the symbol was listed after X, Y, Z as “&: per se, and.” Meaning “&: in itself, ‘and’”, and inevitably pronounced as “and per se and”, it’s a quick corruption to “ampersand,” and the rest is history.

The Dawning of the Age of Content - and why Content Convergence Matters to You
For anyone watching the way information is now created, collated and distributed on the world wide web, this article will ring true. We ARE all watching what is going on, aren’t we?

We’re all content producers. And we’re all about to live through interesting times with the dawning of The Age of Content. Industry is discovering content as a commodity, as inventory with value, and the rules are changing fast.

The new rules are not just for high-profit content like movies and music. What was once seen as the lowliest form of commercial content within an enterprise - technical manuals, support documentation, and other business content - is starting to take its place alongside other valued corporate assets.

The 10, 20, 30 Powerpoint rule
An oldie but a goodie, it’s often quoted but it’s worth re-reading (especially as I’ve just pulled together a presentation that has.. eh… 23 slides.. ). It’s not always applicable of course but well worth keeping in mind.

It’s quite simple: a PowerPoint presentation should have ten slides, last no more than twenty minutes, and contain no font smaller than thirty points.

Summer of Doc, anyone?
Janet has a good idea for getting student technical writers (and hey why limit it?) a little bit of experience.

Now in its fourth year, Google Summer of Code supports students in writing code for participating open-source projects, which provide mentors to help guide the students’ work. Thanks to Google’s sponsorship, the students receive a stipend (making this a summer job), and mentors receive a nominal compensation for their time.
…
If you substitute code/documentation, developers/tech writers, Computer Science/Technical Communication, I think it’s fairly obvious that the same benefits could apply to Tech Comm students writing documentation for open source projects.

And finally a nice quote from the late great Douglas Adams:

” I love deadlines. I like the whooshing sound they make as they fly by. “

Blimey, another week has flown past and, as ever a few things have caught my eye.

9 ways to gather user feedback
It’s often a struggle to get true user feedback on your documentation, Craig Haiss offers some suggestions to improve things in this area. Whilst I’ve tried some of these, and had heard of them all, it’s worth a look to jog the memory:

You can write the most detailed instructions in the world, but if they aren’t the instructions users actually want, you’re wasting your time. That said, how do you go about gathering feedback to flesh out your documentation?

Tech Comm Job to Job Title: Something Lost in Transit?
Ben Minson is musing on job titles and, as well as raising a giggle, ends up stuck. Job titles, as a way to convey what you do for a living, are important.

… the dictionary says one who documents is a “documentalist”—however, I’m reluctant to adopt a job title that includes the word “mental.” So this is where you get “documentation specialist.” The same goes for “usability specialist.”

It seems a little funny that, being writers at heart and therefore professional manipulators of language, some of the terms we pick for our field don’t easily translate into job titles.

I’m currently experimenting with the title “Technical Information Manager” which is a little OTT but seems to fit my current role, thankfully my company, like myself, isn’t hung up on formal job titles (they prefer that you, you know, get on with whatever needs done). So, what’s your job title?

Typography humour

Glossary of DITA terms
Bob Doyle is wondering if there should be a central, user-maintained, glossary of DITA terminology:

many DITA-related terms are not defined … They are simply assumed.
And some is insider jargon, like reltable for Relationship Table.
And there is no convenient alphabetical listing.
You can search for terms on the DITA Infocenter, but then you have to already know the term.

This got me thinking. If you have been toying with setting up a documentation Wiki, then this may be an excellent place to start. It might also throw up some interesting usage of terminology. Definitely something I’m going to have a stab at (well, I’ll add it to the list of things to try).

RoboHelp vs Flare
Interesting round up of posts and comments on this topic. If you use, or are planning to use, either product, give it a look.

And I’m done. Another week in the wonderful world of Technical Communications has gone, I wonder what next week will bring?

Text Preferences Survey
What is the ideal text size to use on the web? What about line height and column (line) length? Most of the information in this area is based on print (at best) or anecdotal (at worst). A design agency in Brighton, Message, has decided to try and find out by carrying out a survey:

“Our goal is to publish a report that provides hard facts about what constitutes ‘readable’ text on the web … We see this report being of value not just to our clients and their customers but to web users at large.”

It only takes a few minutes to complete so go and take the survey.

Why software applications need product blogs and why they don’t get them
As well as having a very long title, Tom also hits on some points well worth considering if you are at all web savvy (and I’m presuming that, as you are reading this blog, you are). Most of his ideas are spot on but would require a lot of business process change, but I think they are worth picking up on:

I can think of six major ways product blogs can benefit users and project teams. Product blogs can …
- Provide a venue for product announcements
- Allow users to submit product bugs
- Allow users to submit feature requests
- Provide a roadmap preview for the product
- Enable a point of connection between users and project teams
- Provide a way to teach advanced tips to users

He also mentions something that I too have pondered, namely including RSS feeds in online help and somehow merging the two in a more dynamic way than before. Probably not much point in purusing that now but who knows what may happen in the future.

How to work better
A short list of simple, but powerful, advice which is applicable to everyone. Go on, there is at least one thing on that list that you could do better (or if you are like me, 3 or 4).

Subversion for writers
Entirely focussed on Mac OSX users, this has reminded me that we use Subversion at work and that I should really write up our process. Regardless of platform, the basic benefits of using a version control system can be realised with little cost.

What does it do? It manages multiple versions of a project in development. You check your project out of the repository, make changes and you commit those changes back to the repository. At any time you can view older versions of the whole project or of individual files, and revert to them, if the work done since was in error. You can make branches, which allows you to develop your work in two (or more) ways in parallel, and you can tag your project to say, at this point I met a certain milestone (eg: first draft, second draft, version sent to publisher X, version sent to publisher Y, published version, etc.)

Another week has zoomed past, and I’m only now catching up! I’ve been helping out with our development group retrospectives… but more on that later. For now, here are a few things that caught my eye this past week.

Gatekeeper vs. team member
Whilst not directly talking about technical writing, there are some good points in this post, with several mirrors between some of our [sic] processes and that of the self-publishing author:

…some authors, trusting no one but themselves, will put out what they have to say, untouched by any other person. Sometimes this works. Usually it doesn’t. Others will reject the criticism of experts but accept the flattery of a subsidy publisher. Others will embrace the traditional publishing process and accept the input of those who have more publishing experience than they. Others fall along the full spectrum in between.

Is single source always the best option?
Single source, rightly, gets a lot of press and for a lot of companies would be of benefit. However it can be hard to convince others of those, here’s an example:

I know a single source of content will save me a lot of work. But for other people in the company it won’t. It will mean more work for them, not to mention a very steep learning curve, an investment in software and a strong training committment. It will save me lots of time and effort—in the long run—but it’s going to double the work effort of ten other people. Where is the benefit?

The last business case I pulled together this was the sticking point as well. Understanding the pain points, and how much they cost the company is key and the benefits need to be realised over a longer time period than you’d think.

Are you part of the industry conversation?
Anne Gentle (via Twitter) pointed out that Sun now have a formal blogging policy in place for their employees. It’s a great step and shows that they understand the role that blogging can play:

… By speaking directly to the world, without benefit of management approval, we are accepting higher risks in the interest of higher rewards. … The real goal isn’t to get everyone at Sun blogging, it’s to become part of the industry conversation.

Confluence Wiki adds page ordering
I’ve talked about Wikis before, and largely I think the core value comes through long-scale collaboration and, as such, haven’t really considered moving our documentation set to a wiki. There are very good cases for wiki-fying your documentation set of course, but for me there are one too many limitations. This news from Confluence is starting to change that as summed up by Sarah:

When you’re writing a documentation set, the sequence of the pages and chapters is very meaningful. It’s nice… well, many would argue that it’s essential to be able to define a logical page order rather than being stuck with an alphabetical order. Up to now in Confluence, we’ve worked around the problem by manually adding chapter numbers and page numbers, like “1. Introduction”, “2. Installation Guide”, “2.1 System Requirements”, and so on. Now take a look at point 2 in the Confluence 2.8 Release Notes. We can just drag and drop the pages and chapters where we want them. They stay there :) and the new order is reflected in the PDF outputs and hierarchical page-tree views

Thinking like a user
I spend a fair amount of time reminding developers that they have a different mental model from (some of) our user base and that the design may be improved by taking the point of view of the target user. However I should confess that I fall into the very same trap myself:

the problem with being able to think like a user is that familiarity breeds … well, familiarity .. we’re using (at least I hope we are) the applications that we document daily … building a store of information about the application [and] we can easily lose sight of what the new user, who comes to the application tabula rasa, may experience.

Yup. Guilty!

Word 2003 Tip: Edit in Print Preview mode
I didn’t know this one either. You truly do learn something new everyday.

Ahhh, the end of another week (well it will be in a few hours, just a few last diagrams to be rebranded…), which means it’s time for a quick roundup.

Pilcrow & Capitulum
A nice little post for the font freaks (guilty!) discussing the evolution of the that little symbol that is often used to mark the end of a paragraph.

It’s tempting to recognize the symbol as a “P for paragraph,” though the resemblance is incidental: in its original form, the mark was an open C crossed by a vertical line or two, a scribal abbreviation for capitulum, the Latin word for “chapter.”

Open Applications – A Model for Technical Documentation?
Ferdinand Soethe takes a look at the Open Source movement and finds several parallels and arguments for basing a technical documentation effort on the same principles. It’s not all a perfect match but this confirms some of my own suspicions.

Talking with Technical Editors on the topic of Single Source Publishing (SSP), one sometimes gets the impression of talking about Utopia. (Nearly) everyone knows it, nearly everyone could well use it in their work, but hardly anyone actually uses it.

The necessity to prepare contents for different target media can neither be really met with classic text processing or DTP systems nor with Web design tools. This was why the XML language family born in the 90’s found huge acceptance in the area of Technical Documentation.

Rethinking Community Documentation
An old but still valid and fascinating article exploring the changing landscape of technical information:

The way we educate ourselves to use and program computers is shifting along many of the same historic lines as journalism, scientific publication, and other information-rich fields.

As an industry much has changed in the two years since Andy wrote this article but it’s still worth a read, particularly if you are looking at launching your own technical community initiative.

Three Ways to Get Developers to Keep You up to Speed
A simple reminder of how to get things done, the kind of advice that sometimes seems very obvious until you read it and realise you aren’t doing it! I’m tempted to print out the three “rules” and pin them to the wall.

Get support from those whose voices everyone takes seriously. Chances are, you were hired because someone thought documentation is important. You may find yourself in an environment where you have to prove your importance, and many times that is a battle fought for a matter of inches rather than miles.

As ever, I’m keen to hear about any other technical writing/communications focussed blogs, in any area. If you write about your job, regardless of your industry, do let me know.

Been a while since I did one of these and, as ever, they reflect some of the things that have caught my eye over the past week or so. A couple of things on DITA which have me rethinking my approach towards it, and a some links to posts discussing … welll community, social media, Web 2.0 kind of stuff, some of it is a little away from my world but it’s good to get a different point of view on these things.

Docbook versus DITA
Not the first comparison I’ve seen but an excellent summary comparison of DocBook versus DITA. Whilst it was written by someone who admits that they were looking to portray a favourable outcome for DocBook, it’s an well-balanced set of information and will be useful to many.

From Free to Three ($100K)
One of the issues I have with DITA is the cost associated with implementing a complete end to end solution, something that, apparently, I’ve been mistaken about:

Our DITA Tools from A to Z section on the DITA Users website lists every software and service up to those $300,000 publishing solutions. But our policy of free member access to online tools means that anyone anywhere in the world can at least get started (our membership fees range from free to $100 a year).

We call our approach “DITA from A to B,” authoring to building and, of course, publishing structured content.

Definitely something I’ll be checking out.

Agile Content Development

Social media represents such a fantastic opportunity because it allows us to create and launch media properties directly to the public. But even more of a blessing is the direct and indirect feedback process that naturally happens in this space.

You put something out there, and the crowd will reveal the direction you should go. It’s not necessarily always the wisdom of the crowd, but rather the desires and objections of the crowd that guide you.

Use of social media needs fear

What about all of the fears of potential liabilities, losing control, and (the night terror) negative comments? IRRELEVANT! All are either uncontrollable (and were all along) or can be mitigated with good policies, procedures and education. Social media carries as much risk as email. You should be more afraid of losing the battle for relevance.

Is IT in danger of becoming extinct?
I’m not entirely convinced but, once again, this post suggests that there is a shift of balance, and that shift is entirely driven by users and their new found abilities to build communities around, or away from, your products.

Social media empowers users at the expense of IT. Enterprise 2.0 companies marginalize IT by putting powerful tools directly into the hands of non-technical workers, bypassing IT in the process.