Technical Writing

Tutorial : Creating distinct documents from the same DITA XML source (conditional text)

olivier — Thu, 15 Mar 2012 13:11:57 +0000

DITA XML offers a powerful conditional text mechanism which favors sharing content and minimizing redundancies. This tutorial will help technical writers use DITA conditional text in a few minutes.

Prerequisite:

You have installed DITA Open Toolkit in the DITA-OT1.5.4 directory under GNU/Linux or Windows.

Paste the following file under a text editor and save the file as conditional-text.dita in the DITA-OT1.5.4 directory:
Using Conditional Text Warning for electricians Shock hazard Do not touch electric wires. Warning for plumbers Drowning hazard Do not dive in the sink. Any content located between tags which does not contain an audience value excluded in a .ditaval file appears in documents meant for plumbers and electricians.

Note the DITA tags that contain distinct audience values: we will exclude the content located in one of these tags depending on the audience key when we compile the target file.
Paste the following file under a text editor and save the file as conditional-text.ditamap in the DITA-OT1.5.4 directory:
Conditional Text Sample
Paste the following file under a text editor and save the file as electricians.ditaval in the DITA-OT1.5.4 directory:
Paste the following file under a text editor and save the file as plumbers.ditaval in the DITA-OT1.5.4 directory:
Open a terminal, then enter the following command in the DITA-OT1.5.4 directory:
java -jar lib/dost.jar /i:conditional-text.ditamap /filter:electricians.ditaval /outdir:. /transtype:pdf2

Open the conditional-text.pdf file, it contains informations meant for:

Plumbers and electricians
Electricians only

Enter the following command:
java -jar lib/dost.jar /i:conditional-text.ditamap /filter:plumbers.ditaval /outdir:. /transtype:pdf2
Open the conditional-text.pdf file, it contains informations meant for:
- Plumbers and electricians
- Plumbers only

You’ve just compiled to distinct target file from the same source file by only changing the filter value in the compiling command.

DITA XML Resources

olivier — Wed, 14 Mar 2012 07:22:43 +0000

This section allows to set up a free DITA XML authoring and publishing chain.

Tutorial: Creating valid DITA XML content with nXML mode

olivier — Wed, 14 Mar 2012 07:12:16 +0000

nXML mode provides continuous validation and completion for DocBook, XHTML and other XML documents. You no longer need to know the XML schema by heart: nXML assists you in entering an element name, attribute name or data value allowed in the current context. It does not support DITA XML by default, however. This tutorial will help you using this Emacs mode to create DITA XML documents.

Prerequisite:

Emacs
The DITA XML documentation project directory structure must be as follows:

.
└──
    ├── concepts
    ├── faq
    ├── reference
    ├── tasks
    └── topics

where the value is en_US, or fr_FR, etc.
Command line instructions are meant for GNU/Linux ; they must be adapted for other environments.

Backup your whole DITA XML documentation project.
Open a terminal, then paste the following set of commands:

cd && wget http://www.thaiopensource.com/download/nxml-mode-20041004.tar.gz && tar xzvf nxml-mode-20041004.tar.gz && wget http://www.technical-writer.org/media/nxml-mode-environmment.txt && cp .emacs .emacs.bak && cat .emacs | sed '$a\' > .emacs.tmp && mv .emacs.tmp .emacs && cat nxml-mode-environmment.txt >> .emacs && rm nxml-mode-environmment.txt

If you are prompted that the .emacs files does not exist, paste the following commands, then repeat this step:

cd && touch .emacs

This set of commands:
- Downloads and uncompresses the nXML mode archive
- Create a backup copy of the .emacs file (.emacs.bak)
- Writes the nXML mode environment variables in the .emacs file
Download the DITA XML Relax NG schemas archive in your DITA XML documentation project root directory.
Change to your DITA XML documentation project root directory, then paste the following command:

tar xzvf rnc.tar.gz

This command creates a rnc directory at the same level as the .
Download the schemas.xml files archive in your DITA XML documentation project root directory, then paste the following set of command (replace by the actual name of the language directory en_US, or fr_FR, for instance). Repeat this step for all your language directories.

tar xzvf schemas.technical-writer.org.tar.gz && cd && cp ../schemas.technical-writer.org/concepts/schemas.xml concepts/ && cp ../schemas.technical-writer.org/faq/schemas.xml faq/ && cp ../schemas.technical-writer.org/reference/schemas.xml reference/ && cp ../schemas.technical-writer.org/tasks/schemas.xml tasks/ && cp ../schemas.technical-writer.org/tasks/schemas.xml tasks/ && cp ../schemas.technical-writer.org/topics/schemas.xml topics/ && rm -rf ../schemas.technical-writer.org/

The schemas.xml files are now located in your language directories, for instance:

.
└── en_US
    ├── concepts
    │ └── schemas.xml
    ├── faq
    │ └── schemas.xml
    ├── reference
    │ └── schemas.xml
    ├── tasks
    │ └── schemas.xml
    └── topics
     └── schemas.xml
Open a DITA XML (.dita) content file with Emacs.

The DITA XML syntax is highlited. Invalid parts of your document are underlined in red.
To insert a new tag, enter <, then press Ctrl+Enter.

The list of allowed tags appears.
Select a tag, then presse Enter. Press Ctrl+Enter to display the list of allowed attribute names.
To instert a closing tag after your text, enter

Tutorial: Automating DITA XML multilingual documentation projects management

olivier — Thu, 08 Mar 2012 09:59:36 +0000

DITA XML is a great tool for managing technical documentation. However, multilingual projects require creating a distinct .ditamap (table of contents) file for each language. This can lead to inconsistant multilingual versions. Fortunately, this problem can be solved with an appropriate methodology and a publishing script for the DITA Open Toolkit open-source publishing system.

DITA XML multilingual documentation projects methodology:

The .ditamap file must not include navtitle sections, which contain a hard-coded title instead of extracting the title from the corresponding DITA section, and can therefore not be shared accross distinct language versions.
As soon as you start the DITA project, save content (.dita) files in language-specific directories. For instance :

. └── product └── en_US ├── images ├── tasks └── topics

instead of:

. └── product ├── images ├── tasks └── topics
In the .ditamap file, replace all instances of the language directory by a unique transitional chain of characters, for instance, @language-code@:

instead of:
To publish target files, you can now:
- Edit the default.locale value in demo/fo/build.xml
- Replace the unique transitional chain of characters by the language directory name in the .ditamap file
- Edit the language parameter (xml:lang) in the .ditamap file and in the DITA content files
- For PDF target files, edit the page size (US letter or A4, for instance) depending on the target language
- Publish target files
- Restore orignal values in source files.

5 Minutes Windows Tutorial to Getting Started with DITA Open Toolkit

olivier — Wed, 07 Mar 2012 05:46:04 +0000

This DITA XML tutorial will help you set up and use the DITA Open Toolkit open-source publishing system under Windows (tested on Windows XP).

Duration : 5 minutes

Download Java, then launch the installation program.
Download DITA Open Toolkit 1.5.4 on the desktop, then unzip DITA-OT1.5.4_full_easy_install_bin.zip.
Press the “Windows key” and the letter “R”.

The Run Dialog Box appears.
Type cmd

and press OK.

A terminal window appears.
Paste the following command in the terminal window,then press Enter:

cd Desktop\DITA-OT1.5.4_full_easy_install_bin\DITA-OT1.5.4
Paste the following command in the terminal window, then press Enter:

startcmd.bat
A new terminal window appears.
Paste the following command in the new terminal window, then press Enter:
java -jar lib/dost.jar /i:samples/taskbook.ditamap /outdir:. /transtype:pdf2
This command creates a PDF file from a DITA XML sample project.

Congratulations, you've just compiled your first DITA XML project! The taskbook.pdf target file is located in the Desktop\DITA-OT1.5.4_full_easy_install_bin\DITA-OT1.5.4 directory. Skip steps 1 and 2 to compile new projects.

5 Minutes Linux Tutorial to Getting Started with DITA Open Toolkit

olivier — Mon, 05 Mar 2012 06:59:21 +0000

This DITA XML tutorial will help you set up and use the DITA Open Toolkit open-source publishing system under GNU/Linux (Ubuntu or Debian).

Duration : 5 minutes
Prerequisite:

Ubuntu or Debian on a physical or a virtual machine with administrator password
Internet link

Open a console, paste the following set of commands, then press Enter:

cd && wget http://downloads.sourceforge.net/project/dita-ot/DITA-OT%20Stable%20Release/DITA%20Open%20Toolkit%201.5.4/DITA-OT1.5.4_full_easy_install_bin.tar.gz && tar xzvf DITA-OT1.5.4_full_easy_install_bin.tar.gz && wget http://www.redaction-technique.org/media/dita-env.txt && workingdirectory=`pwd | sed "s/\//slash/g;"` && perl -pi -e "s/personal-dita-home/$workingdirectory/g;" dita-env.txt && perl -pi -e "s/slash/\//g;" dita-env.txt && cp .bashrc .bashrc.bak && cat .bashrc | sed '$a\' > .bashrc.tmp && mv .bashrc.tmp .bashrc && cat dita-env.txt >> .bashrc && exit

- OK, the code may be more elegant, but it works and saves you quite a few steps -

This set of commands:
- Changes the current working directory to your user account root directory
- Downloads the Dita Open Toolkit archive
- Uncompresses the Dita Open Toolkit archive
- Downloads the Dita Open Toolkit environment variables file
- Writes your user account root directory in the Dita Open Toolkit environment variables file
- Makes a backup copy of the .bashrc file (.bashrc.bak)
- Appends the Dita Open Toolkit environment variables at the end of the .bashrc file
- Closes the current console
Open a new console to take into account the new .bashrc version, then paste the following command:
sudo apt-get install openjdk-6-jre ant

and enter the administrator password. Press Enter at the Do you want to continue? [Y/n/?] prompt.

This command opens a new administrator (root) console.

Note: On a Debian system, if you are not sudoer, type su -.

This set of commands installs Openjdk 6 and Apache Ant.
Paste the following command:
cd DITA-OT1.5.4
This command changes the current working directory to the DITA-OT1.5.4 directory.
Paste the following command:
java -jar lib/dost.jar /i:samples/taskbook.ditamap /outdir:. /transtype:pdf2
This command creates a PDF file from a DITA XML sample project.

Congratulations, you've just compiled your first DITA XML project! The taskbook.pdf target file is located in the DITA-OT1.5.4 directory. Skip steps 1 and 2 to compile new projects.

If several Java versions are installed and an error occurs, open an administrator console and select the Open JDK 6 version:

# update-alternatives --config java Selection Path Priority Status ------------------------------------------------------------ * 0 /usr/lib/jvm/java-6-openjdk-i386/jre/bin/java 1061 automatic mode

You can specify one of the following values for the transtype option:

Value	Target Format
xhtml	xhtml
eclipsehelp	Eclipse help
eclipsecontent	Eclipse content
javahelp	Javahelp help
htmlhelp	Windows compiled help
pdf2	PDF
troff	troff
docbook	DocBook
wordrtf	Microsoft RTF

User Guide

olivier — Thu, 23 Feb 2012 16:12:11 +0000

User Guide: helping clients, attracting prospects

Technical documentation is notoriously known as something of no use when you try to start your brand new vacuum cleaner. Though it is seldom regarded as a marketing tool, user guides are the documents clients read the most.

Sales engineers often use user guides as a sales argument, if the technical documentation takes into account pre-sales. Within the company, technical documentation then changes its status from a costly after-sales service to an efficient marketing tool.

Journalists also use users guides to find detailed information about a solution and test them alongs with the product. User guides are seldom communicated to the larger public. The technical level of a user guide depends on the technical expertise of its audience. But a good user guides is always as simple as possible.

Contact

olivier — Wed, 22 Feb 2012 08:53:15 +0000

Olivier Carrère, Technical and Marketing Writer

LinkedIn Profile

To send me a message:

[contact-form-7]

Technical Communication

olivier — Wed, 22 Feb 2012 06:34:12 +0000

Whether in print or on the web, marketing and technical communication tools must hit their target audience, then prove them the high-tech enterprise’s solutions fully answer their needs. Technical communication’s and the technical writer’s role is to create and publicize high-quality content to convert prospects into clients and increase user satisfaction.

Technical and communication may sound like antonyms. But high technology enterprises’ communication tools always associate technical writing and marketing communication. Every marketing document is highly technical: it is otherwise not credible. And every technical document is also a marketing tool: otherwise, it is of no use to the company.

Technical communication is often mistaken with technical writing. Technical writing helps clients to use the products and is then a post-sale service. Technical communication is also a pre-sale, marketing activity and helps market, sell and use products all along their life cycle. It is not only meant for users, as technical writing, but also for prospects.

Technical Communication aims at showing how a product answers its target’s needs. To this end, it uses a number of tools, depending on the technical level of the audience and its relation with the company (general public, journalists, prospects, clients…). The technical writer must adapt to each audience. He uses all technical communication tools (writing, image, animations…) to help better market the product.

Leveraging content means:

Creating high quality content fitted to its target
Keeping every content revision
Reusing or recycling content effectively

Can one be at the same time logical and creative? This is necessary in such areas as musical composition, architecture and software development. It is also the case in technical communication.

This requires:

Studying the target needs and the company’s means
Having strong writing and creative capabilities
Managing projects efficiently
Creating and leveraging content according to an industrial process

This web sites presents some technical communication tools, their marketing value, how they fit audiences needs and their creation processes.