one man writes
one man designs
one man blogs

Archive of RecentlyRead posts

 
 

Recently Read

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.)

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.

Recently Read

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.

Recently Read

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.

Recently Read

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.

Recently Read

“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?

Recently Read

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.