Tag: <span>Recently Read</span>

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.


Comments closed

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.


Having been ill for a couple of weeks I’m just catching up with my reading list and there have been some fascinating posts and articles to read. Quite a few of them struck a chord and I’ll need to give them some more thought before I tackle them myself but all in all it’s a pleasure to be able to read such insightful posts from some very smart people. Ain’t blogs wonderful.

The agile technical writer
An excellent write up of the typical processes followed by a technical writing team in an Agile environment. It’s good to read this kind of thing, as it matches roughly what we do so… we must be doing it right?

In a similar vein I’ve recently written up an article for the ISTC Communicator magazine which outlines what I consider an average day in my working life. Naturally there is no such thing but the things I do, and the processes I follow match Sarah’s.

Interesting quote from Matt Haughey

My ideal blog engine company would hire some seasoned blogger and technical writer to be a documentation czar, keeping docs up to date when new versions are launched, produce screencasts for introductory users, and provide complete documentation at a stable URL that applies to every version of the product.

Moving legacy documentation to DITA
Scott pointed out this interview with Joann Hackos and, as ever, she offers sensible advice, particularly as I’m in the midst of planning such a move (to AuthorIT, not DITA):

Among your previously existing information, some of it we may call legacy because it documents products that are not changing much. Much of this information isn’t worth changing. There’s low value in converting or updating it.

The History of Visual Communication

Visual communication is the communication of ideas through the visual display of information. Primarily associated with two dimensional images, it includes: art, signs, photography, typography, drawing fundamentals, colour and electronic resources.

I’ve not read more than a couple of pages but this is fascinating and worth a look if you are at all interested in information design of any type.

Developing documentation, the FLOSS way.
Found on the DMN blog, this looks at the creation processes for documenting Open Source Software:

The common challenge is to create useful FLOSS documentation in a timely manner. The documentation must be continually updated as the software and projects evolve. It must be simple to understand yet comprehensive. The documentation must be easily translated into dozens of languages. It must be easily revised and distributed in a variety of display and publishing formats (HTML, PDF, PostScript, etc.).

Some handy tips and thinking points for anyone looking to streamline (and speed up) their content creation processes.

Writing in times of resource constraints
Mike Hughes offers some sage advice with some business perspective applied to the resourcing issue many of us face:

If your resources are tight, ask yourself whether you are writing the essential stuff at a level of quality users will notice

“Good enough” documentation is a reality that many of us don’t like to admit, but there are good reasons to understand when it is applicable to use that benchmark.


“Don’t know what I want, but I know how to get it”
Jeff Patton revisits the basics of Agile development, and one section leapt out at me.

Saying “shippable” to people in the customer role means implies they’d better get the requirements right because that’s the way Agile development works.

Now, I believe Agile people had something else in mind when they said it. I think they mean keep code quality very high. Keep the code supported with unit and acceptance tests. Take steps to validate each and every user story. It tells testers to get involved earlier and more continuously. It tells developers to develop with a higher attention to quality. (Apparently developers would be developing crap otherwise?)

Which is all well and good, but isn’t there something missing? Hello? Product Documentation?? Regardless of his omission (an oversight, I’m sure) If you are involved in a software team using any form of iterative, Agile development then give it a read.

Collison’s Ignorance Spiral
After every release cycle has been complete, we undertake a Retrospective, looking back at what went badly and what went well, with the aim of carrying forward the lessons learned into the next release. I think we are pretty good at it but some of what Chris says is interesting:

I’ve been in a number of lessons learned reviews where the intent of the meeting seems to be catharsis for the team or compliance with the process, rather than learning for the organisation.

Is that such a bad thing? Sometimes the discussion is more important than the outcome, and if the team needs catharsis then surely it’s better to provide an outlet for it? Admittedly I’m taking what Chris wrote and skewing it somewhat, but he makes some good points.

Top 10 Distraction Stoppers
Nice list of useful applications, particularly item 5 “Minimise your Word Processor”. One of the commenters suggested an application called q10 as an alternative to Darkroom for Windows.

I’ve been trying out q10 recently, mainly for the posts on this blog and for an article I’m currently writing, but I’ve slowly been extending it to other things and I have to say it is very effective. It takes a bit of getting used to but if you have problems focussing on your writing, and I mean REALLY focussing, then it might be worth a look.

Project Blogs, Email and Dual Collaboration Channels
Written in response to a separate post, this paragraph leapt out at me:

A larger question is how to efficiently manage processes that, for historic or practical reasons, require collaboration among multiple communities that maintain a mix of potentially incompatible formal and informal communication processes.

It’s something that we repeatedly visit at my place of work, we have a very successful wiki, and we’ve started to ponder if there are other tools out there that might benefit us in other ways.

In my head there is a need for something like Twitter but with the ability to post slightly large amounts of information (not much, say double the character count). That way anyone can post a quick thought for the consumption of others. Very informal but possibly a good way to capture the myriad of ideas that are generated each day?


Comments closed

Christmas looms large, and the days are “fair drawing in” as they say in these parts. I’m taking a couple of weeks off to relax and recharge, and no doubt to eat, drink and be (very) merry. As ever this time of year is pretty hectic, so here are few things that caught my eye over the past couple of weeks.

10 Word to avoid in your writing
A short list but the main point is to avoid gobbledygook. One of my pet peeves is the use of long words when a perfectly valid, shorter, word is available. The Plain English website has some excellent advice if you want to find out more.

No-one reads the help anyway

the next time you hear someone say, “No one reads the help anyway,” say, “Yah, no one uses Google either.”
This will lead to a puzzling follow-up question — What do you mean? I use Google all the time.
Then you say, What do you use Google for? To search for answers, solutions, and information when you have questions?

Like some of the commenters, I disagree with this a little. At a simple level it works, but there are flaws. However, as an opening gambit I think it’s a good one. It will make people stop and think, and once you have them thinking about it THEN you can explain the more subtle differences.

AuthorIT Yahoo Group Search
I’m listing this here so I don’t lose it again. Yahoo Groups are great but the search engine frequently falls over. MANY many thanks to Hamish for providing this resource, this is the kind of thing that makes the Internet great.

Building a successful web community

Do not assume that a community, particularly a successful web community, is easily built from the one ingredient of a shared interest – ensure there is also a goal or a purpose in the mix.

Very true. I know that some Technical Communicators are starting to thinking beyond user documentation, and the next step may well be to nurture online communities around your product. This article has some good tips, and I can vouch for them all having struggled to setup a Scottish Blogging site myself.

Technical Communicators and UI Design
Scott Nesbitt spotted an article about User Interface Design and a particular section caught his eye. It states that the documentation must be considered as part of the design, and Scott goes on to say:

“technical communicators need to get involved not only in the design and usability of an interface, but also how users will access documentation from within the interface.”

I couldn’t agree more with this, and recently I’ve been pushing my team to think along these lines, realising that we work with, and develop, “information” rather than “documents” meaning we need to have a greater sphere of influence.

To coin a phrase, we are the interface to the interface.


Tomorrow we get to spend the afternoon in the pub after gorging ourselves on turkey and stuffing. Yes, it’s the Development Christmas Lunch. This year it’s handily placed right at the end of a release cycle (although that does mean some poor souls may be dragged back into the office), so we can celebrate the release AND the birth of a baby a long, long time ago (or whatever you believe).

That also means that next week I’ll have a little more free time to think about the future, and get some plans in place. I’ve already got a fair list, some of which will feature here.

However, for the time being, here are a few things that caught my eye the past week (or so).

Writing Tips for Non-Writers Who Don’t Want to Work at Writing
As THE core skill of my job, some of this is a little hard to take but sometimes we can be a little too obsessed with grammar, don’t you think?

Grammar matters, but not as much as anal grammar Nazis think it does … Frankly, I think if most non-writers can manage to get agreement between their verb and their subject, I’m willing to spot them the whole “who/whom” conundrum.

Wiki Patterns: The Book
I love it when this happens, a blog I’ve read for ages (devoured some would say) gets published in book format. Needless to say my copy is already ordered.

Human behavior is pattern-based, and wikis are designed to support the
patterns of activity that occur when groups work together. Therefore, there’s no right or wrong way to use a wiki, so it’s impossible to write a recipe for successful wiki use that will work in all cases.

Instead, documenting the behaviors seen on different wikis and classifying those that help the wiki effort as patterns, and those that hinder the wiki as anti-patterns, is a more useful
way to offer guidance to other wiki users.

Use Structured FrameMaker and WebWorks ePublisher?
Sticking with Wikis, here is an excellent article from the WebWorks Wiki: Implementing Help-Specific Features with a FrameMaker EDD.
I probably learned more about using Structured FrameMaker with WebWorks reading that article than I have in the past year of actually using both products in anger (although that’s mainly because the set up here works so I’ve not had to tinker).

This project contains a complete workflow for producing printed and on-line documentation with ePublisher Pro. At the heart of the system is a structured FrameMaker template with an underlying EDD. The minimalist EDD contains a scant nine content elements and yet automatically assigns more than 120 paragraph styles that implement help specific-behaviors in the corresponding ePublisher Pro template.

Building Enterprise 2.0 on Culture 1.0

Sounds a bit odd I know but if you are interested in how to build an collaborative environment in your organisation then you must have a look.

To encourage an organisational shift along the enterprise collaboration maturity model, Enterprise 2.0 leaders should focus on capturing the flow of information. Over time, the flow builds not only a stock of searchable knowledge but also a reputation as the source of fresh ideas and trusted up-to-date content.

And finally, a little house-keeping. I had promised to update the OPML file of TechComms RSS feeds but I’ve not had a free minute. It’s top of the list now though, so expect to see an update early next week.


With the TICAD conference last week, a couple of days in my sick bed, and the imminent product release I’m working towards, I’ve not had a lot of time to post here. However, the RSS feeds keep trickling in, so here are a few items that caught my eye over the past couple of weeks.

What Beautiful HTML Code Looks Like
I’m a terrible coder. Which is just as well because I’m not a developer but as I do dabble in HTML and CSS quite frequently (hey, and PHP too), then this is a good reminder for me to develop my own best practises.

Code is Tabbed into Sections: If each section of code is tabbed in once, the structure of the code is much more understandable. Code that is all left-justified is horrific to read and understand.

Includes a neat infographic, downloadable as PDF, which is now pinned beside my desk.

Procedures: The Sacred Cow Blocking the Road
An update on a (yipes) 10 year old article. I don’t think I read it when it was first published but I have read it. Well worth another visit though.

“It takes a surprisingly short amount of time for a user to feel unstuck. When I was a usability consultant, I used to advise clients to put the critical information in the first three words of a sentence.”

IA Deliverables
From Content Surveys, to wireframes, Personas and Use Cases, a brief overview of each is followed by a sample template. Not only a useful resource but a good overview of the typical process an Information Architect will undertake, a lot of which can be adapted to more traditional product documentation.

Collaboration is not a dirty word
Collaboration on content (not documents, even if that is where the content ends up) was a key part of my presentation. It’s good to see the switch from document-centric to info-centric taking place.

I love things being this easy. I love getting (almost) zero emails with attachments. I love not having a hard drive full of Word documents.

DITA Troubleshooting specialization

The Troubleshooting specialization creates a new topic type that is well-suited for problem-solution information.

7 Ways to keep the post-conference buzz
Not long back from a conference myself, I have already done a few of these things (item 3 in particular) but some good ideas here.

Wikis for Documentation?
Steve Manning isn’t sure about using Wikis for Documentation but does think they could be a big hit in another, related area:

Most writers have to guess about their users. Few writers get the opportunity to speak directly with users. Few get any sort of feedback at all. They are left to do their best. How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask?

I totally agree. All I need to do is figure out how this works within a single source environment, and tackle a few issues around governance and change management and it could be an excellent working model.

And finally…
I’ll be updating the TechComms RSS feeds download soon, so if you think you should be on the list (or even if you aren’t sure whether you are or not) then let me know. It includes all kinds of stuff which is loosely related to Technical Communications, and I’m always on the lookout for more sources of inspiration. Leave a comment if you think of anything.