Monday, June 23, 2008

New updated DITA ecourse released (finally)

Tomorrow (or possibly tonight) we'll be releasing the updated version of our popular ecourse "An Introduction to DITA".



  • Updated to reflect the changes in the DITA standard

  • Updated to reflect the changes in the DITA Open Toolkit from version 1.3 to 1.4.2.1

  • Updated to reflect the changes in the downloading processes for installing the various tools associated with DITA.

  • New audio to improve the quality of the voiceovers


  • DITA (Darwin Information Typing Architecture) is certainly the most talked-about development in the field of user documentation. If you are involved in writing documents such as user manuals, procedures or online Help, DITA promises you a framework for designing and delivering well-structured content efficiently and consistently in a single-sourcing environment.

    See An Introduction to DITA.

    Labels: ,

    Friday, June 20, 2008

    Brent Hoberman on the three biggest trends

    I was Codrin's leaving party last night (he's emigrating to Switzerland), so I missed Brent Hoberman's presentation at Ecademy's event in London. Brent is well known in the UK as an Internet pioneer, as a founder of Lastminute.com.

    Andrew Wilcox, a mind mapping expert, did attend, and his notes from the event show that Brent talked about the three biggest trends businesses should watch out for.

    Brent said those trends are likely to be:

    1. Location based mobile information
    2. New screen technology, promising paper-equivalent resolutions
    3. Video IPTV

    All these trends could be incorporated into user assistance, such as online Help. So will we see technical authors using these capabilities at some stage in the future?

    Labels: ,

    Thursday, June 19, 2008

    Six ways to add Web 2.0 functionality to your manuals

    This is an end of a long day post, so forgive me if I miss anything obvious. Here are some suggested actions and ideas for creating Web 2.0 technical documentation:

    1. Put your documents on the Web, as Web pages.
    2. Create a link to the Web version on folksonomy/tagging sites such as Digg, Technorati and del.icio.us. Describe your content on these sites (using tags).
    3. Consider aggregating/incorporating content from other sources into the online version. This could be content from other departments, such as support, or external content. You can use RSS feeds to acquire this content.
    4. Create a RSS feed for your content. This can help users be aware when content has changed, and help them re-use the content elsewhere. You could use Feedburner to do this.
    5. Create a Twitter account and link your RSS feed to this account. This means users who are also Twitter users can receive your updates through Twitter. You can use Twitterfeed to do this.
    6. Consider enabling users to add comments to your content. Some Help authoring tools allow you to add this functionality. Others allow you to embed this functionality from elsewhere. Another potential way to do this could be by using the Adobe Air viewer.

    What about wikis? Wikis can be a good idea, particularly if you want to use content from development staff. However, you need to consider how you control and approve content and how you create printable manuals.

    What is Web 2.0?


    We 2.0 is name for a collection of Web technologies that can be summarised enabling conversation, aggregation and collaboration.

    Why add Web 2.0 functionality?


    That's a whole conversation in itself, but the benefits include establishing a better relationship with your clients and prospects and getting others to write some of the content.

    Have I missed anything out?
    Should you take this advice?

    Labels: , ,

    Monday, June 16, 2008

    Ten Challenges for Technical Authors in the Network Age

    The Supernova 2008 conference is currently running in San Francisco - on the theme of "the Network Age". Professor Kevin Werbach has outlined ten challenges:



    "In the Information Age, computers and communications networks produced a global village and astounding gains in economic productivity. The Network Age incorporates those advances into an environment where anything connects to anything, anyone to anyone, anywhere, anytime. We’re not all the way there yet, but we’re far enough along to start seeing the effects... The Network Age poses ten basic challenges for all of us interested in the future of technology, media, and communications:

    Scarcity and Abundance
    (Both are sources of value, yet they cannot coexist.)

    Choice and Coordination
    (Users are in control, but don’t they need guides to avoid being overwhelmed?)

    Aggregation and Fragmentation
    (Network effects mean that the big players get bigger, but at the same time, markets increasingly specialize and personalize.)

    Stability and Disruption
    (True innovation requires disruption, but disruption can be painful and costly, especially where investment and trust are significant.)

    Behavior and Rationality
    (People don’t always act according to models of rationality, especially when connected to one another, but our economic frameworks assume they do.)

    Complexity and Simplicity
    (Complex adaptive systems produce emergent behavior and growth, but simplicity is a virtue… in both life and information technology.)

    Openness
    (Everyone agrees it’s good, even essential in a networked environment, but no one can say what exactly it means, or how much openness is beneficial.)

    Governance
    (How much do networks and their users need to be managed or protected, and where do those controls come from?)

    Scale
    (The local is different from the global, whether the subject is enterprise collaboration or usage patterns or cloud computing infrastructure.)

    Sustainability
    (How to build organizations and systems that endure, especially in a world whose delicate ecology is itself a form of scarcity.)"

    Are these the challenges we will face in the future?

    Labels: ,

    Friday, June 13, 2008

    Is this video on advertising-customer break up also true for technical communication?



    Brian Solis, Principal of FutureWorks PR and New Media agency in Silicon Valley, has posted a blog on the need for organisations to listen directly to the needs of the customer.

    Solis states:

    "You can’t manage a relationship, you need to be a part of it, fully engaged...

    ...If a conversation takes place online and you’re not there to hear or see it, did it actually happen?

    The customer comes first, and if we fuse sociology, social media, customer service, relationship marketing, experiential marketing, and traditional marketing, we’re creating a new formula for outbound influence and fueling a new generation of brand ambassadors and loyalists."

    Is this also true for technical communication?

    Labels: ,

    Tuesday, June 10, 2008

    Failure in technical communication

    JK Rowling made a great commencement speech recently at Harvard University - on the topic of failure.



    Failure is something that stalks the world of technical authors.

    Failure affects our clients. Users often have to feel they have failed before they call up online Help. It is said that Microsoft nearly renamed "Help" in Vista, as a way of encouraging users to call it up more. However, they couldn't find a better word than "Help".

    Failure is viewed differently in other cultures. I remember Patrick Hofmann talking in 2006 about how people from Japan read and re-read instructions carefully before they start a task, so that they won't make any mistakes. "Bodge", a typically British word, has no direct translation into the German language.

    Should technical authors be comfortable living in a world of failure?

    Jo Rowling's presentation illustrates that failure is part of life. Failure can have benefits as well as drawbacks. Maybe we should "re-frame" our world to something more positive. Where people fail, technical authors, through what they create, are there to help and assist.

    Labels: , ,

    Friday, June 06, 2008

    Trends in Technical Communication - Peering into the crystal ball

    I'm starting to think about a conference presentation I have been asked to make later this year. Sometimes, our talks are about "big picture" issues, such as "what makes a good technical author?" or "what's the value of documentation?", and I'm currently considering whether I should talk about the future trends in technical communication.


    The two current trends in technical communication


    There seems to be two trends in technical communication, at the moment.

    The first is the move away from a craft-based approach to creating documentation, and a move towards a more "engineering" based, methodological approach. It explains the interest in and move towards single-sourcing, XML, DITA and such like. It promises more efficient writing processes, faster "time to market", but little change in what the end user actually receives.

    The second trend is the adoption of Web 2.0 technologies to provide user assistance. I've heard it also called "free documentation", "right to remix", the "democratisation of documentation" and "tech writing 2.0". I don't think any name has stuck yet, apart from the generic "Web 2.0". It's a trend that promises a major difference in what users actually receive as user assistance.

    We describe Web 2.0 as having three main themes: the aggregation of knowledge; collaboration on content creation; content as conversations (and linked to that, the wisdom of the crowd).

    When I presented on Tech writing 2.0 at the end of 2006, the major developments mostly related to the aggregation of content across the Web. Today, the biggest developments seem to be with conversational content.

    It's content that is, today, being created away from the Technical Publications department.

    What does this mean to technical communicators?


    I think the questions technical communicators should be keeping in the back of their mind are:

    1. Should I be adopting and embracing these trends?

    For some organisations, particularly those with a small user base or a small authoring team, the answer is NO. It's hard to see where the participation and the benefits will come from. However, will that mean their documentation will look inferior to more mainstream software?

    2. Can these two trends be unified?

    Will these trends converge? Will Web 2.0 content rip apart all those carefully laid plans for a single repository for all your content?

    3. Who will take on the role of editor?

    Who will keep all this information in order? Maybe you will need to take on the role of an editor.

    The correct answers, I believe, have yet to emerge.

    What else should I be reading apart from the Cherryleaf blog?


    Take a look at these articles:
    Why Do People Write Free Documentation? Results of a Survey by Andy Oram
    The State of Free documentation, by Adam Hyde
    The state of free documentation by Anne Gentle

    What do you think?

    Labels: , ,

    Wednesday, June 04, 2008

    Open source economics

    In this video, Yochai Benkler explains how collaborative projects like Wikipedia and Linux represent the next stage of human organization.



    Is he right? Could the same economic rules be applied to the technical writing projects, where there is a large user base?

    Labels: ,