Category Archives: xml

The DITA XML authoring barrier for non-Technical Authors

Posted on by
3

One of the challenges for organisations moving to a new content management system for their user documentation is selecting an authoring tool that is:

  • powerful enough, and
  • can be used by non-Technical Authors as well as the professional Technical Authors.

Many organisations want staff, such as developers, to be able to add content to the system directly – without having to pass it over to the Technical Publications department. The difficulty lies in that many tools for authoring in DITA and other XML schemas are daunting to those unfamiliar with the underlying principles of DITA and structured content. It’s even more challenging if you’re someone who is only going to write content occasionally.

One approach is to create templates, with defined fields that need to be filled in. Another is to get staff to write in Word, again in conjunction with a template, import the text into the content management system and then map metadata and other semantic information to the content at that stage.

Is it an unsurmountable problem? Should we just accept that writing semi-structured XHTML content (such as wiki-based content or WordPress-like authoring environments) is a better compromise? What you lose in modularity, you gain in having an easy-to-use authoring environment. Alternatively, do we need to recognize we’ll always need specialists who can convert text into the appropriate format - the equivalent of the typing pool or typesetters?

It has bearing on the role and value of Technical Authors. Is it their main value in writing skills, information management skills, editing skills or in using a specialist tool? If the organisation believes “everyone can write well”, then is their value in using software that’s complex and tricky to use?

Dr Tony Self’s DITA training courses in London

Posted on by
Reply

We’ve arranged for Dr. Tony Self to host his DITA training workshops in London this October. Tony is based in Australia, and he also known as “Dr. DITA”, as he has a PhD in DITA. He is also the author of “The DITA Style Guide”.

Publishing with the DITA Open Toolkit, 8 October 2012

Most DITA implementations start with the DITA Open Toolkit (OT) being used for publishing of DITA content. The Open Toolkit is developed and managed separately from the DITA standard itself, and provides an open-ended collection of tools and sample files. Although some DITA tools provide alternative publishing paths for DITA content, many DITA authoring tools rely on the OT.

In this workshop, you will learn how to install, configure, test, customise, and publish DITA documents using the DITA Open Toolkit. Along the way, you will discover why the OT appears to be complicated and quirky. You will also learn its relationship with DITA, and how it is typically integrated with a DITA authoring tool. The OT’s command line publishing interface is quite daunting for many, so you will also discover how the free WinANT Echidna tool can provide a friendly, feature-rich interface.

We will work hands-on to explore how to provide customised PDF and HTML output and corporate “badging” of output. A number of third party plug-ins extend the functionality of the OT further, and we will also experiment with some of these useful extensions.

DITA authoring best practices, 9 October 2012

As more companies implement DITA to streamline the development of documentation and user assistance, best practices for DITA authoring are being established. While the OASIS DITA standard provides rules for the use of elements and attributes, it does not provide clear guidelines for how to practically apply the mark-up, and how to create consistency so that DITA documents can be more readily interchanged. DITA has the potential to change habits of composition, expression and presentation for a broad range of writers and in so doing enhance productivity across a number of industries and occupations.

Adopting best practices will enable authors to maximise their productivity. In traditional authoring, best practices are often captured in a style guide, providing real-world examples and clear recommendations. However, existing style guides are written for style-based authoring, and not for DITA’s semantic mark-up approach. Tony Self has analysed the way in which DITA has been used, and has developed a DITA Style Guide to fill the gap between the DITA standard and traditional style manuals. In this workshop, Tony describes what constitutes best practice in DITA, explains the rationale behind the commonly used DITA elements and structures, and works through practical examples of best practice decisions.

The workshop will also cover the basics of DITA authoring. It is aimed at authors new to DITA and experienced authors wanting to improve their practices.

Cherryleaf XML DITA workshops October 2012 – your opinion needed

Posted on by
1

We’ve arranged for Dr. Tony Self to host a few training workshops in London this October. Tony is based in Australia, and he also known as Dr. DITA, as he has a PhD in DITA and is the author of The DITA Style Guide.
http://www.scriptorium.com/books/the-dita-style-guide-best-practices-for-authors/

We’d love your feedback on which XML and DITA training courses we should offer:

  • Should we offer an introduction to DITA, or is everyone now familiar with it?
  • Do you want to know more about publishing from XML?
  • Is there an aspect of XML and DITA you’d like to know more about
  • What course would you want to attend?

Do let us know!

Any user guide, as long as it’s black

Posted on by
2

At last week’s UAEurope conference (and in this season’s Communicator magazine), Dr. Tony Self suggested how car manufacture can be an allegory for the technical communication profession.

Henry Ford revolutionised car manufacture when his production line replaced the method where cars were hand-made by artisans. Famously, Henry Ford offered the Model T in “any colour… so long as it is black”.

There are parallels in technical communication. Many technical communicators are still clinging to hand-crafted documentation, creating custom layouts and “tweaking” formatting, when new modular methods are vastly more efficient. The age of offering documents in any “colour” the customer wants is over. And just as car manufacture has long since moved to automation, technical communication too must embrace automation, with XML providing the technology platform to make this possible.

I think there is even more we can learn from car manufacturers.

While the Model T was initially a success, Ford was slow to replace it with a new model, and by 1930 the company had been overtaken by General Motors. Ford, had, in effect, created a very efficient process for creating something that almost nobody wanted.  The process was inflexible and it took them a year to introduce the successor, the Model A. So perhaps, technical communicators need to make sure what they produce efficiently is what their customers actually want.

In addition to learning from Alfred P. Sloan (the head of General Motors at the time), we can also learn from today’s car manufacturing processes. Today, many manufacturers use Lean manufacturing. Lean focuses on stripping out waste – if something does not add value to the customer, then it is eliminated. In other words, Technical Communicators need to quantify and demonstrate the value of their documentation to the customer, if they want to use car manufacturing as their model for the future.

What links spy scandals to technical writing?

Posted on by
1

Answer: Context. Someone recently said “content is king, but context is queen”. This is true when it comes to actions as diverse as spying and writing technical documentation.

We can illustrate this using scenes from the World War II film “Went the day well?”. It’s a story about spies and “fifth columnists”.

The importance of WHO is asking a question:

Words can have more than one meaning:

The importance of WHEN something is said:

Finally, here’s a non-spy, example in German. The film “Keinohrhasen” illustrates the importance of past actions. Note: this film had a 15 certificate.

The challenge for writers is write content appropriate to the context in which it is being used. The Semantic Web, and to an extent DITA XML, promises to automate this, but, in the meantime, your writers need have a good understanding of the context as well as the content.

Technical writing company creates single source cost reduction calculator

Posted on by
3

We’ve added a further simple online calculator to the Cherryleaf Web site. This one is for calculating the potential savings in support costs derived from a single sourcing content management system.

See our Single Source Cost Reduction Calculator page.

We’re also developing a more comprehensive spreadsheet to help you measure the value of documentation. Contact us if you would like a copy.

The “Beyond Documentation” Webinar videos

Posted on by
Reply

Scriptorium Inc has uploaded the “Beyond Documentation” Webinar Ellis delivered back in August 2009. In this session he looked at the future of technical writing and likely changes to the ways in which user assistance is delivered.

We asked:

  • Are we moving beyond documents?
  • If so, what does this mean for technical communicators?

Part 1:


Part 2:

Part 3:

Part 4:

Part 5:

You can see more videos on Cherryleaf’s YouTube channel.

 

Once more, but with meaning – how will the Semantic Web affect technical documentation and technical authors?

Posted on by
2

Web technologies expert, John Fintan Galvin, is claiming 2010 will be the year of the Semantic Web, when semantic technologies really take off. If that is the case, how could it be used by technical communicators to deliver better user assistance?

The Semantic Web is all about the automation of connections between “resources” in a context-sensitive way. These connections can be made between anything defined as a resource, e.g. topics in a Help file, chapters in a user guide, other content, data, people, systems etc.

In the past, we’ve talked about how it will allow for more intelligent searching. 

However, the Semantic Web also offers technical authors the opportunity to automate the republishing of content (e.g. extracts of a user guide) across the Web – in all the places where this content could add real value to users.

Let’s look at some possible examples:

  1. When someone poses a question in a Newsgroup or user forum concerning ”adding a new user”, a summary of the relevant information from the user guide appears automatically in the right hand column of the Web page.
  2. When users from ABC Inc. view the online Help for Oracle 11, they see links to the topics that have been judged the most useful by other ABC Inc. staff.
  3. Users see Beginner, Intermediate or Advanced user information, depending on their individual status or preferences.
  4. When someone raises a Support ticket, a summary of the relevant information from the user guide and/or the latest status on any similar support calls, appears automatically next to the form.

In such an environment, technical authors would need to do much more statistical analysis of what users want and how they behave – both modelling scenarios and analysing behaviours. This means looking at your chunks of user information (resources) and asking:

  • What could we connect our content (resources) to?
  • To whom could we connect it?

It also means that the content will need to be stored in a way that makes it possible to categorise the content semantically and to republish the chunks of information in a semantic format.