ffeathers — a technical writer’s blog

Yesterday I attended the first techfest organised by OLPC Australia. It was a full day of talks, demonstrations and workshops aimed principally at people who might want to get involved on the technical side. I’ve come away with much more knowledge of the OLPC project itself as well as the hardware and software involved on the server and laptop sides.

The day was hosted by Pia Waugh and Jeff Waugh, with talks and workshops by Martin Langhoff and Joel Stanley. There were about 30 people, I’d guess. Most of the interest was in the technical side of things, but I did talk to a teacher who had travelled and worked in various African countries and is now working in Aboriginal Education in Sydney. For her, it was the educational aspects of the project and the instructional design of the hardware and software that are important.

In case anybody wants to know how you can get involved with the project, I’ve highlighted some bits in purple italics below.

Some terminology:

• OLPC — One Laptop Per Child. The OLPC project aims to give a specially-designed computer laptop, the XO, to children in remote and underprivileged areas of the world. The goal is to give these children access to the most up-to-date technologies for learning, experimentation, self-expression and collaboration.
• XO — the laptop provided to school children.
• XS — the server at the school.
• Sugar — the user interface i.e. the screen design, behaviour and tools which the XO presents to the children and other users.
• Activity — an XO application or program, such as Draw or Chat.

One of the breakout sessions at the end of the day:

e-Learning and challenges

The day’s first talk was an overview of e-learning and its challenges by Martin Langhoff. He covered the key factors arising from educational research, which drove the design of the XO and the thinking behind the OLPC project. We zigzagged between educational theory, anecdotes and technical specifications.

I didn’t get a good photo of Martin, but there’s one on the OLPC web site.

Here is some of the educational theory:

• Kids figure things out. Particularly when in small groups, where there’s a bit of competition, a lot of collaboration and the opportunity to teach others what you know. This happens better away from the classroom.
• Sugata Mitra’s Hole in the Wall project illustrates this concept. He made a hole in a wall which bounded a slum in India, where a number of children live and many do not attend school. On the other side of the wall, he placed a computer with internet access. The children could access the computer via keyboard and mouse. Within a couple of weeks, they were Googling for their favourite Bollywood starts. In a few more weeks, they were Googling in English.
• Constructionism is based on the discovery that we learn most when we are preparing material to present to others. This applies to small children too.
• The laptop’s user interface, Sugar, latches onto a child’s natural curiosity. It’s easy to get started, but the tools quick challenge the children by providing layers of complexity that are quite readily visible. For example, you can start developing a computer program with Turtle Art (a drag-and-drop way of moving chunks of code around) and then move into the Python programming language itself, via the XO’s “Pippy”. The names and terms line up with each other on each layer, so children quickly discover that a deeper layer is just a different and more flexible way of doing the same thing. Children start playing, and soon start giving adapted versions of the laptop’s inbuilt “activities” (applications or programs) to their friends. There’s more about the XO programming environment in my earlier blog post about OLPC in Sydney, and of course in the OLPC wiki.

Here are some of the environmental factors:

• The XO laptop is destined for remote areas, often with little or no power or connectivity. This demands non-conventional product development. For example, the laptop goes to sleep aggressively; avoids frequent polling, e.g. it doesn’t ask every 200 milliseconds what the battery status is ; and is able to deliver something useful even if there’s no or sporadic connectivity. There’s more about the XO hardware in my earlier blog post about OLPC in Sydney, and of course in the OLPC wiki.
• It would be useful for a school to have a way to request information from a website by URL, when the school does not have connectivity. Martin calls this “the return to waffle or UUCP”. The idea is that a messenger (someone who is travelling between the remote settlements and larger villages) would carry a USB stick with such requests. The messenger would go to the nearest point of internet connection and plug in the USB stick. A tool would crawl the requested websites and put the content on the stick, which the messenger would take back to the school server. This would also give the OLPC a chance to deliver patches and other updates to the school server.
• Interesting point: The XO has built-in hardware to act as a USB key. You’d just need to activate the software.

What about content — what information is or will be contained on the laptops and/or school servers? The project will be making a lot of use of Wikipedia. Here’s one place where people other than developers can help. They need good-quality content, principally in simple English or Spanish. Information about local culture is useful. Localisation of content to the small regional areas is very valuable.

Another way to contribute is to try out the new activities that developers are creating and give feedback. You can get a Sugar emulator. If you’re on Linux, they say that’s easy. Otherwise, you need to install vmware first.

Wiki slices

Martin mentioned this concept in his talk and I’ve put it in a section on its own because it’s so interesting.

The problem: There’s so much information out in the world. Even if you restrict yourself to Wikipedia (ignoring all debate about Wikipedia as a source of information), there’d still be a problem putting the whole of that single repository onto an XO laptop or an XS server. (More about the XS below.)

The OLPC has spearheaded the concept of a wiki slice as a way of delivering a cut-down set of information in a compressed format. The plan is to devise a set of scripts to select the appropriate information. For example, you might score the articles by popularity to decide what should be included in the cut-down information set. There’s a page on Wikipedia for the WikiProject Wikislice now too.

My thoughts: I work at Atlassian, which produces the Confluence wiki. At the moment, the wiki slice project is aimed at MediaWiki, which powers Wikipedia. I wonder how much work it would be to adapt the scripts to work on Confluence, or on other wikis? Also, we’re often asked about offline use of the wiki content. Could the wiki slice technology be useful outside OLPC?

“Unsupported legacy operating systems”

And the Microsoft Windows thing? According to Jeff Waugh, that’s just not relevant. Martin’s view was similar: The OLPC project is just forging ahead. The answer to doomsayers is along these lines:

We’ve done it. We are shipping laptops. Over 100 000 laptops are out there now, in the hands of children or being distributed.

At the moment, they’re working towards distributing 240 000 laptops in Peru, to between ten and fifteen thousand schools.

The OLPC project is not spending time on Windows integration. They’re also not stopping it. They have implemented a dual-boot option, which will be made available to those countries who want it. Windows will come on an SD card, at an extra cost of USD 10 ($3 for the operating system plus $7 for the card). If you boot with the card in, you’ll get Windows otherwise the XO will boot Linux. OLPC does not intend to prevent countries from loading Windows onto the laptops. Freedom of choice is integral to the world of open source.

What’s a pity is that the dual-boot feature will negatively impact the fast suspend/resume feature of the BIOS. The current version aggressively goes to sleep when not in use and resumes fast when needed.

Perhaps, when countries see that it doesn’t really work to use an unsupported legacy operating system, this will all blow over

OLPC Australia

In the second talk of the day, Jeff Waugh told us about the goals and status of OLPC in Australia. The goal is to support OLPC-related activities on this side of the planet. This will extend the reach of the project, because we are close to countries in Asia-Pacific region which need the XO and we are also close to people who are keen to contribute.

Jeff and Joel:

Areas of interest are:

• The Pacific
• Remote Australia
• Regional and metropolitan Australia.

OLPC Australia aims to build up a community of people who can contribute:

• Educators
• Technical people to deploy the laptops and servers
• Fund-raisers

Trials are being set up at the moment in metropolitan and regional schools, in Northern Territory and remoted Queensland, and in the Pacific. They are looking for volunteers to help set up the deployments. The work would be for a few weeks in one or two months’ time.

Jeff says that the project has had a good response from government. The current government aim is that “98% will have access to the National Broadband Network”. Geoff’s response is, “We are the other 2%. And we are an education project.”

Senator Kate Lundy took an XO to a Labor Party meeting. Kevin Rudd liked it. We know, because the XO took a photograph of his smile.

Jeff sees a huge opportunity in the Intervention project, and there are two state education departments interested.

OLPC Australia is looking for corporate sponsorships. As yet, there is no framework, but they are interested in any organisation which can give a concrete idea of how it can help.

OLPC Australia will also replace some of the content on the XO with Australia-focused information, such as the wiki slice content which deals with US presidents.

Live a life of XS - the school server

The third session was presented by Martin Langhoff covering the XS, or school server.

Until now, deployments have used standard server setups. Peru will be the first major deployment with the new XS which Martin is working on. At the moment, the focus is on infrastructure, backups of the XO laptops and configuration management tools. They also plan to look at security in more detail.

The physical design of the box caters for high temperatures. It will either hang, or rest on an integrated stand. The machine itself will take up one third of the space, the other two thirds will be just air flow. No fans.

Due to the unique nature of the project, a radically different administration model is needed. This is interesting to any system administrators out there. Martin is basing his ideas on models used at NASA, among others. Tools are based on the work of Steve Traugott and his infrastructures.org.

It’s a client-pull model, due to the problem of sporadic connectivity. The idea is that the servers keep track of which machines have managed to pull down the updates, so that the others can be manually updated via a USB stick.

There will be little or no end-user interface on the server. Initially, a technician will configure the server via auto-install. The server will be shipped to the school. With a bit of luck, someone at the school will plug it into a power socket. And that’s it.

Power supply may be sporadic. So the server needs to be able to roll back to a safe state if an update finished unexpectedly. Everything must just work. Martin calls this,

turning a complex server into an appliance.

What about passwords? How do we deal with the fact that a small team of technicians will be looking after thousands of machines? It’s not a good idea to have a master admin password that works for all time over all machines. The solution: At installation of the server, it will generate a list of one-time passwords which are unique to the server. This list will be stored at the network operations location. When the technician goes to a particular server, he will take a USB stick with ten or so of the passwords. This minimises the impact of a lost or publicised password.

On the collaboration side, Moodle is central to the server. MediaWiki is also used for asynchronous collaboration (as opposed to the synchronous collaboration supported by the XO laptop). The plan is to have several wiki slices running on the server, either independently or within MediaWiki.

Martin is also looking at content repositories. They need some way of sharing content among the schools. The content might be developed by teachers, an education department or even the children. The repository must be lightweight and distributed. It will support SCORM and IMS packages. World organisations such as WHO may even provide content this way.

Martin talked about the complexities of programming where you must look at long-term support, as opposed to regular updates being possible.

We can’t distribute emergency patches to the laptops or servers. After doing each bit of programming, we must consider all the important failure scenarios. This is very challenging.

A note also, that the laptops are independent of the servers. You can think of the server as an extesion of the laptops, providing backups, extra content, etc. When there are up to 20 or 30 laptops together, they communicate via the mesh networking — the “bunch of laptops under a tree”. When there are more laptops in the group, the server acts as a mesh portal, coordinating so that the network runs more efficiently.

Gung ho on the XO — the laptop

Joel Stanley gave the final talk of the day, before we broke up into groups to look at the machines themselves.

Joel ministering to an XO:

Joel gave a technical overview of the machine, starting with a look at its innards. We hopped from chip to chip, and a lot of it went over my head. Some snippets:

• You can now have mesh networking on your PC at home, by downloading the kernel module. It’s known to work on the B43 chips but they’re still ironing out problems with the Intel chip.
• The XO screen is trans-reflective i.e. it bounces incoming light off a mirror behind the screen to enhance the display. The next generation won’t need power at all to display the screen.
• The next generation of XO will support e-books like Amazon’s Kindle.
• The current software stack requires 256Meg of memory. This could be reduced, but that would take additional developer time.
• The XO includes a 1-gig hard drive.

The star of the day

XO closed:

Rotated screen:

eBook mode:

Side view, with a Samsung mobile phone:

Innards of the XO:

XO screen showing the Neighbourhood. Each little figure represents another XO or a shared activity:

XO screen showing the activities currently loaded. This one shows (going clockwise from the top) two instances of Turtle Art, Draw, the always-present activity at the bottom (I’ve forgotten what it’s called), two instances of Chat and the Distance activity:

XO screen showing the Distance activity. Two laptops can measure the distance between them by blurting sounds at each other:

My conclusion

The OLPC project is interesting on so many levels — technically there’s a lot of innovation and scope; but also politically, socially, economically and philosophically it’s one of those grand schemes that come along rarely.

When I first saw pictures of the XO laptop I was disappointed, because it looks a bit like one of those pretend-computers that you give to toddlers. It’s not. Those are toys. The functionality is limited to what is pre-programmed into the box. In contrast, the XO is a serious collaboration and learning tool which intrigues developers as much as children. In fact, it aims to rub out the line between the two.

Links to more information

• My earlier blog post about OLPC in Sydney
• OLPC Australia web site and blog
• OLPC project web site
• Documentation on the OLPC wiki

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. At today’s first session, Tony Self introduced us to AIR (Adobe Integrated Runtime) and two prototype AIR Help applications.

Tony is a founding partner of HyperWrite. His sessions are always amusing and information-packed. This one was no exception.

AIR

First, Tony introduced AIR itself. The acronym stands for “Adobe Integrated Runtime” and is produced by, you guessed it, Adobe.

In brief, here’s what happens:

• As an author/developer, you will create an AIR application.
• You will send the application to your users — it’s just a single file (extension .air).
• Your users will install the AIR platform first, then install your application.

Since Adobe has such a wide following and presence, it’s thought that the AIR platform will soon be as prevalent as Flash, i.e. approximately 97% of computers will have AIR installed.

Here are some of the things AIR does for you:

• You can create a rich desktop application, including graphics, HTML, AJAX, Flex and Flash.
• An AIR application can be installed and run on any operating system. Well, in principle anyway.
• Your application can include content from local and remote sources. Tony mentioned a good use case here: Your application could fetch the online documentation from the server if your user is online, otherwise it could default to the local copy of the documentation.

Two AIR Help applications

Next, Tony gave us an demonstration of two uses of AIR to produce online help systems:

• Scott Prentice’s prototype AIR Help application
• Adobe’s pre-release AIR support for RoboHelp 7

Scott Prentice’s prototype AIR Help application

Scott Prentice has created a prototype AIR Help application, using a DITA document as a test case (the DITA language reference). Scott’s application allows you to view the DITA document in a rich desktop viewer. The navigation panels include two different tables of content, an index and a search.

Adobe’s pre-release AIR support for RoboHelp 7

Adobe is building AIR support into RoboHelp 7. Currently, this is available as the pre-release RoboHelp Packager for Adobe AIR. The packager is free, and likely to remain so. It is also open source. It will probably become another output option in the RoboHelp UI.

To use the packager now — assuming you have RoboHelp installed:

• Download and install the AIR platform.
• Download and install the RoboHelp Packager for Adobe AIR.
• Generate your WebHelp output from RoboHelp as usual.
• Then run the packager, giving the location of your WebHelp files as input.
• You will need a digital certificate. When you distribute your application, your users will use the certificate to verify the source of the executable file. For testing purposes, the packager leads you through the process of generating a certificate on your own machine. When you eventually distribute your AIR application, you’ll need a certificate from a recognised authority.
• You can set various look-and-feel options, such as number of tabs, skins, branding. The number of available options will probably increase when the product is more mature.
• You can configure your application to allow your users to add comments. Wow, Web 2.0 (More below.)
• You can also configure it to update the local AIR Help file periodically from the server.
• Click the “Generate” button — the packager will produce a file with the .air extension. This is the file you will distribute to your users.
• Your help application supports context-sensitive help.
• You can also bundle the help application with the product (application) it is documenting.

Now put on your other hat and become a user of your help system. Double-click the generated xxx.air file to install it.

• You should see the content of your help file in the AIR Help viewer. It will look very similar to the RoboHelp WebHelp output. After all, it’s the same HTML.
• It includes a search facility, which also shows a summary of the contents of the pages in the search results.
• There’s also an index.
• It allows users to add “Favourites” — this is difficult to do in straight HTML-based help.
• The “How do I” facility is similar to RoboHelp’s Browse Sequences.
• There’s a sophisticated zoom utility to increase text size.

A bit more about the comments in the Adobe AIR Help

When you use the Adobe packager to create an AIR Help file, you can configure your application to allow your users to add comments.

A user can then add comments to the help topics. By default, the comments are stored on the user’s local machine. Each user can see a list of and review their own comments. They can also choose to synchronise their comments with the server. Then their comments are visible to other users, and they can see other users’ comments.

Tony mentioned that this is a bit of a trend in online help software, for example MadCap Flare can now run with the MadCap Feedback Server, which collects comments as well as information about how the users are using the system. This is useful, for example, to diagnose troublespots in the help system and the application it is documenting.

My conclusions

Tony’s session was very interesting to me, because I’ve produced various help systems such as WinHelp, HTML Help and straight HTML files, using RoboHelp, Help & Manual, HDK and others lost in the mists of time From the little bit I’ve seen today, AIR Help is one to keep an eye on. It’s not a leap into the future, but it has some useful advantages over CHM files and vanilla HTML.

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. In one of the sessions today, Sarah Goodall walked us through a DITA application developed and implemented by Tactics Consulting under consultation with Tony Self from HyperWrite.

This session was interesting as a practical application of DITA and as an application which is not primarily a technical documentation system. Tactics developed a DITA-based system to create and store proposals. Before the new system was implemented, the creation of proposals was largely a manual process involving copying and pasting information from similar proposals in Word documents. This could lead to inconsistencies and even inaccuracies.

The proposed solution was a single-source XML-based solution. Tactics chose DITA because they saw a lot of commonality between DITA and Information Mapping, the technology used and promoted by Tactics. It was relatively straight forward to map DITA information types to the Information Mapping types. Also, Tactics was keen to use an open source solution, and one that they can share with their customers.

As a next step, Tactics plan to move even further into single sourcing, by drawing their web site content from the same source as their proposal documents, brochures, etc.

Sarah’s presentation was interesting from the technology side of things. She also mentioned other aspects of the project, such as change management — moving the staff to the new procedures and technologies.

A couple of snippets:

• Elkera XML Print is an Australian product that renders DITA into Microsoft Word.
• I raised the point that people often don’t like to see the same information thrown back at them in different media. For example, if they see some information on a brochure they might go to the web site for more in-depth information or to see the same information but worded differently. They find it annoying to see exactly the same words. So while you can use conditional tagging to include more or less information, would you also need to ensure that the wording itself is different and is this a design consideration? Sarah Goodall replied that Tactics will continually test their users’ responses to the content, and supply different content for different media if necessary.

Thank you Sarah (Goodall) for an interesting and useful session!

BTW, there are eight Sarahs at this session, in a total of 65 attendees

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. One of the sessions today covered web technology and standards, presented by Joe Welinske.

Joe is the president of Seattle-based WritersUA. This is the second of his sessions that I’ve attended. The first is covered in my earlier blog post, on trends, tools and technologies in online documentation. Today’s session was more technical, covering various standards in the following groups:

• W3C standards such as HTML, XHTML, XML/XSL, Web Accessibility Initiative, CSS.
• W3C hybrids such as HTML 5 (more below), AJAX, RSS and jQuery.
• OASIS technologies — DocBook and DITA.
• Other open source technologies — Oracle Help, IBM WebSphere.
• Proprietary technologies that are still relevant and useful because they are so widely adopted and stable, such as Adobe PDF, AIR and even Microsoft Silverlight (emerging)

As well as talking about the above standards, Joe discussed each one’s possible application to technical communication.

In this blog post, I’ve extracted the subjects that were new to me and a couple of interesting items. Joe covered a lot more than I’ve mentioned here.

HTML 5

HTML 5 is an emerging standard that Joe feels we need to keep on our radar. It’s also known as “Web Applications 1.0″. It includes capabilities that are relevant to technical writers. Specifically, it supports new modular objects as part of a web page e.g. <aside>, <article>, <nav>. So a web page can recognise chunks of content in a non-linear way. Here’s a link Joe gave us to a demonstration: HTML 5 Support by Browser

I found this really interesting, after all the discussion in previous sessions about modular documentation and structured authoring.

Joe thinks that, because HTML 5 has a high amount of interest from some big players, it will probably go ahead.

A question from the floor led to a discussion around HTML’s leniency as opposed to the strictness of XML / XHTML. So HTML 5 may meld HTML’s leniency with the semantic tagging provided by XML. This is potentially useful for the less-technically-savvy authors, because the browsers and other viewers will be instructed to render a page if at all possible even if it contains formatting errors.

Other snippets

Some more interesting items from Joe’s talk:

• Comparison of XML rendering via XSL versus CSS: Printing XML: Why CSS Is Better than XSL.
• Neat use of Flash for an online tutorial, from Verizon Wireless — demonstrates how to use a mobile phone. Click the ‘Interactive “How To” Simulator’. It has a movie of a hand clicking the buttons, plus a block of text in the right-hand panel. The text is in sync with the movie, and you can influence the movie by clicking the text.

My conclusions

Joe covered a huge area in this short session, and his knowledge is huge too. Thank you Joe! The next two days of the conference include other sessions with more detail on some of the areas which Joe has introduced, including one on AIR (Adobe Integrated Runtime) tomorrow.

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. This morning Tony Self hosted a workshop entitled “Introduction to DITA”. I learned a lot, about the DITA schema itself and especially about its application and the team and management structures you might need if you’re planning a large documentation project using structured authoring.

Tony is a founding partner of HyperWrite. He has a wide experience in technical documentation projects and is a skilled and engaging presenter.

A point of interest: Much of the HyperWrite web site is maintained in DITA and is transformed to XHTML when rendering the web page.

This was an excellent session, and there’s far too much content to cover in a blog post. Here are some highlights from Tony’s lecture and the discussions within the class.

Introductory points

These are items Tony discussed before we dived into DITA itself.

• A stated aim of XML is that all human knowledge should be stored in XML. Wow, I hadn’t heard that before. That beats the theory of everything!
• We compared DITA with DocBook. DocBook was developed by O’Reilly as a means of making their publishing process more efficient. It’s now an open standard maintained by OASIS. DITA was originated by IBM, but is now also maintained by OASIS.
• DITA is topic-based. A book, or other publication, is a “collection” of topics. DITA is usually thought to be better for procedures, help systems, and other types of documentation with can be broken down into chunks.
• DocBook is document-based — you might write an entire book in one single file. It’s generally thought to be better for books etc.

Structured authoring

Structured authoring is a whole new way of writing. It requires new procedures, new team structures and new ways of thinking about content. The advantages you gain are things like:

• Content re-usability (one chunk of information can be pulled into multiple different documents)
• Single sourcing (documentation stored in one place and format; can be published to multiple formats)
• Separation of content from presentation

DITA is designed specifically for structured authoring.

A question arose: How can writers make sure that the content they write will fit into the context in which it is used? Tony agreed that this is a concern, and one that is often discussed. In practice, the writer will often be given some context. He says that this concern is probably not as much of a problem as it appears up front.

This discussion brought to mind a web site I saw a few weeks ago, which allows DITA authors to load their documents (i.e. topic collections) onto a platform where others can review the output in its final form. The web site is supplied as a SAAS application. I can’t remember the site URL, and Googling it hasn’t helped. Does anyone know of this site?

DITA itself

Now we dived into the details of content re-use; repurposing via transformations; inclusion/exclusion of conditional text and the creation of a content model.

A question arose: Talking about the content model and the DITA schema, what do you do if the DITA schema does not contain the elements you need for your particular application? In this case, the example was taken from the RADAR equipment industry. Interestingly enough, a committee is currently sitting to design a new content model for the machine industry, which may contain the sort of “warning” elements required by the questioner.

In the wider context, DITA architecture is designed to encourage “specialisation”. You create your own elements to suit your needs. When you need to share your content model with others, DITA supports a process called “generalisation” to make this possible too. The core concepts of “evolution”, “specialisation” and “generalisation” are implicit in the name “Darwin Information Typing Architecture” or DITA.

We did some work on the basic elements of the DITA schema. A point of interest: One of the attendees noticed that many of the DITA elements are similar to the Dublin Core. Tony said that this is by design, for easy interchange.

The big debate around stem sentences

DITA does not allow stem sentences! (Oh dear, the things that technical writers worry about.)

A stem sentence is the short introduction that you might put at the top of a bulleted list, for example. Like this:

To wash the dishes:

1. Put the plug in the plug hole.
2. Turn on the tap.
3. …etc…

In DITA, there’s no legitimate way to add the above phrase “To wash the dishes”. This has led to fiery debate in the documentation community. No doubt it will continue to do so. You could cheat and add the phrase into a <p> element within the <context> element that DITA does allow before the <steps> in a <task>. But this has problems:

• The stem sentence will not be included in the list of <steps>, if you use the <steps> as a unit outside the <task>.
• The stem sentence will be an ugly orphan at the end of <context> if you use <context> as a unit outside the <task>.
• The stem sentence probably duplicates the <title> anyway.

Oh dear oh dear.

So what do you think — are stem sentences a Good Thing or a Bad Thing?

The future

Tony asked what reading formats we might be using in 2010, for example. He mentioned Sony’s BBeB (BroadBand electronic Books). Now all we need is a transformation from DITA to BBeB.

A fun simulation

Try this out: http://www.structuredauthoring.com/simulation

First, do the “Interactive Puzzle” in Part 1. Follow the instructions in the left-hand panel. You will remove all formatting from a web page, bit by bit. Now you can see how difficult the information is to assimilate when the presentation layer has been removed and there’s no semantic tagging. Then Part 2 lets you practise some structured authoring.

A DITA project team

These are the people who might be involved in a large DITA documentation project: the schema designer (if you need to add specialisations to the standard DITA schema); the information architect (creates the ditamap i.e. the structure of the documentation); information developers (these are the content authors); a publisher (defines the data transformation).

Tony pointed out that this specialisation of roles will actually take us back a few years, to before the desk-top publishing era. With DTP, most technical writers create the content, presentation, graphics, and so on. With structured authoring, the information developers are concerned only with the content.

The complexity in designing a topic-based documentation system

If your documentation base is very large, it’s a time-consuming and complex task to design and allocate the topics. Each topic may be re-used in multiple documents, and the topics are written by multiple authors. This needs very careful coordination and management.

Tools

Tony mentioned a number of tools for DITA and other structured authoring, including these:

• XMetaL — authoring environment; an example of a DITA editing tool; includes a map editor (used to build your structure i.e. table of contents)
• Task Modeler from IBM — for design of the maps
• WebWorks — for defining the structure and publishing the DITA topics
• Antenna House — converts ditamaps into PDF
• Author-it — structured authoring; single sourcing; a mature product. But note that its DITA support is output only — you can output DITA but you can’t edit it within AuthorIT.

Tony has also developed his own publishing tool, using the DITA Open Toolkit. This tool handles the publication side of things, not the authoring or structuring. He is interested in any feedback you may have.

• HyperWrite WinAnt

My conclusions

Thank you Tony for a very interesting session. I can certainly see the benefits of DITA as a storage format. The one thing I haven’t yet come across is that killer WYSIWYG editing front-end. With any luck, I might hear more about that in the next few days at the conference.