Blog

How to become a technical writer – Confessions of a former translator

A former translator, I worked the first seven years of my professional life in the translation industry, in various positions. While I learned a lot from this experience, it also left me, as a writer, frustrated. Translators are chained to their source text and writing the words of others in another language, usually focusing on what their clients want. more ...

tekom impressions part 2: API documentation and the VUKA world

Daniela Herbold and Ulrike Parson write about better API documentation and solutions for innovative human resources management. more ...

Impressions from tcworld 2017

Part 1: Improvisation, fluff hunt, and videos for technical documentation. more ...

My first time at tekom

I got back from Stuttgart last night and it is safe to say that after three days of action-packed presentations, writing an article is not in the realm of possibilities right now as I try to connect one synapse with another. more ...

The parson mug prize draw #4. Congratulations to the winners

In which city was the parson mug photographed, we asked at the beginning of September. more ...

Technical Writing with oXygen

For oXygen I have to thank my colleague Mark. He was looking for an XML editor for script programming and downloaded a test version of oXygen. Soon we found out that with oXygen we could easily create XML documentation in common standards like DITA or Docbook. We bought a floating license for the oXygen XML Editor, which we intended to share.

At the same time, some of our customers requested oXygen. We started to use the program productively for authoring. Poor Mark was left with nothing – our floating license was now constantly in use by me. Fortunately, you can always buy more licenses.

Versions

In addition to the full version, oXygen offers two limited versions: XML Developer is suitable for things like schema design and XSLT development. XML Author provides all functionality for writing XML-based documentation. Those looking for a tool to only create standard DITA files, should go for XML Author.

Learning Curve

Technical writers, who have used Word or unstructured FrameMaker so far, may find it more difficult to switch to oXygen. They are probably not familiar with the basic principles of XML-based documentation, such as:

  • Separation of layout and content
  • Thinking in elements and rule-based content structures instead of paragraph styles
  • Variant management and output control using attributes
  • Topic-oriented authoring (not really an XML principle, but used in many XML environments)

Technical writers who have already worked with XML will quickly feel at home. They will also be pleased that they won’t have to install a number of plug-ins or edit configuration files before they can produce a first result (hello FrameMaker!).

Instant Output

What I liked straightaway: I could open a DITA map that I had created in FrameMaker in a default oXygen installation – and at the click of a button, produce a web help and a PDF file. Of course, the results are not yet suitable for publishing. They have to be adjusted to corporate standards. But they are good for a review anyway.

Mouse vs Keyboard

oXygen offers flexible views and handling. Authors who are used to WYSIWYG editors will prefer the Author mode where they can completely hide the XML tags. Authors with a more technical background might use the Text mode that displays raw XML. In both modes, you have many possibilities to add elements and attributes, for example, auto completion, pop-up menus, or catalogs .

Oxygen_DITA

1 – DITA Maps Manager: Lets you edit the map in the tree structure.
2 – Outline: Hierarchical content view, similar to the structur view in FrameMaker.
3 – Editor in the Author mode: Lets you configure which XML tags you see or hide the tags altogether.
4 – Elements Catalogue: At the current position, invalid elements are displayed in grey.
5 – Transformation Scenarios: The currently configured output format.

Perfect Layout?

If I have the choice to edit DITA files in FrameMaker or oXygen, I go for oXygen. The only fly in the ointment: You cannot easily adjust the PDF layout. FrameMaker lets you create templates grafically with onboard tools. oXygen requires knowledge in XSLT or CSS to customize the layout. Plus, you cannot manually manipulate page breaks and the like before printing. But if your focus is on automation rather than a perfect layout, you should be all right.

Add comment


  • facebook
  • linkedin
  • xing