What kind of “easy” authoring are you looking for?

I was reading JoAnn Hackos article on easy DITA authoring solutions and it got me thinking about what the word “easy” means in regard to DITA or any similarly complex technology.

Can an editing interface make DITA easy? Some DITA consultants that I know complain bitterly about tools that make that claim. DITA may be many things, they say, but easy is not one of them. To present it as being easy is only going to set people up for disappointment and failure.

If they are right, can any DITA editor legitimately claim to be “easy”? read more

What is Minimalism?

Ask what minimalism is (in a Tech Comm context), and you are likely to get a recitation of the four principles of minimalism.

Per JoAnn Hackos, the four basic principles of minimalism are

♦ Principle 1: Choose an action-oriented approach
♦ Principle 2: Anchor the tool in the task domain
♦ Principle 3: Support error recognition and recovery
♦ Principle 4: Support reading to do, study, and locate

This is the explanation from the inside. It is equivalent to answering the question, what is a can of peaches, by saying it is a can containing syrup and sliced peaches. What such a definition lacks is the explanation of why you would put something as wonderful as a fresh peach into a can. It is the what but not the why. read more

The Design Implications of Tool Choices

Every documentation tool has a built in information design bias. When you choose a tool, be it FrameMaker, DITA, AuthorIt, a WIKI, or SPFE, you are implicitly choosing an approach to information design. If you don’t understand and accept the design implications of your tool choice, as many people do not, you are setting yourself up for expense, frustration, and disappointment.

Are Docs a Responsibility or a Business Asset?

Do we write documentation to fulfill a responsibility, or to create a business asset? Are we striving to meet a set of requirements pronounced by either convention or regulation, or are we striving to increase corporate revenues and contribute to shareholder value?

The question is provoked by an interesting discussion with Jonatan Lundin in the comments on Tom Johnson’s post Using Tags to Increase Findability. (The discussion has virtually nothing to do with using tags to increase findability — sorry Tom!) Jonatan’s position (if I have understood him correctly) is that tasks can be divided into product-centric  and organization-centric, and that documentation should stick to covering product-centric tasks and not touch organization-centric tasks. My position is that the user’s task is to use the product’s features to meet the organization’s goals and that if we are going to produce task-oriented documentation, therefore, we cannot ignore the user’s business domain. read more