Recently Read

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.

Written By

Long time blogger, Father of Jack, geek of many things, random photographer and writer of nonsense.

Doing my best to find a balance.

More From Author

You May Also Like

Six Thousand

25 Years

Hello 2024