Smart Docs with DITA

Blog A blog about all things documentation as code.

From copywriting to technical communication Technical communication is often reduced to technical writing. Technical writing is intended to provide product documentation, and is involved downstream of sales.

Formats and tools When a company industrializes technical writing, the key issue is not the tool but the underlying format.

The three levels of technical documentation If we compare technical documentation to a garden, we can classify it

KISS Principle of Simplicity The KISS principle (Keep it simple stupid) is a general engineering principle that advocates simplicity to improve reliability, maintenance and scalability.

Is an index useful in a PDF? Full-text search seems to have dethroned the index.

Case study: NuFirewall documentation NuFirewall's documentation, which was perceived by the press as one of the product's strong points, was produced using DITA XML.

Case studies in using DITA XML My daily use of the DITA XML structured authoring format on multilingual projects as a technical writer has led me to develop a number of solutions and tips, which I share with you here.

From document to modular document base The DITA XML structured authoring format offers a way to move from the book model to the modular document base model.

Structured and unstructured formats The information contained in a technical document can be categorized according to its meaning.

A document architecture that's too complex? DITA XML enables productivity gains by reducing the source volume that the technical writer creates, translates and maintains, at the cost of greater complexity.

SQL database In the case of a CMS (Content Management System) such as Drupal, Joomla or WordPress, the repository is an SQL database.

Gathering information Technical writers gather information from various sources, both internal and external to the company.

Content creation The technical writer creates the content of the technical writing project in constant dialogue with the company's various players: R&D departments, marketing.

Project definition Communicating technical information without knowing to whom or for what purpose is a futile effort.

Target format The target format of a technical writing medium is the format in which the message's audience will access it.

Source format Word processors have unaccustomed us to distinguishing between form and content. But confusing the two leads to many errors and wasted time.

Git: from file to content With Git, think content rather than files: it's simpler and avoids many difficulties.

Integrating documentation into development processes. Documentation is part of software.

CMS: workflow as a bonus, but reliability to be tested If they use monolithic formats such as FrameMaker, technical writers can use CMS such as SharePoint, Alfresco or consorts.

Shared network directories - unsuitable for group work Files shared by a technical writing team are often stored in a shared directory on the network.

Version management systems - rustic but reliable Managing text documentation with a version control system (Git, Subversion, SourceSafe) like code.

Delivery The technical writer delivers the document to its recipient in the appropriate manner.

Which repository for group work? To work on a file, the technical writer uses a program that reads the file from his hard disk and loads a copy into RAM.

Repository Content is a company's intangible capital and must be protected as such.

Testing products to document them. A Chinese tale tells how blind people came face to face with an elephant.

Translation Translation constraints must be taken into account upstream of the editorial process.

A single repository? Ideally, all content can be placed under a single repository (e.g. Git) to maximize reuse, consistency and quality.

Using branches in source management systems. Create branches in a source manager to manage divergent projects and documentation translations.

Validation and quality control The content must be validated before delivery.

Create different documents from the same sources via Jinja (object method) Profiling content with Jinja by defining objects (audience, platform, version, etc.) to include or exclude blocks according to their attributes using a Python script profiling.py.

Create different documents from the same sources using Jinja The Python profiling.py script below allows you to profile content in preprocessing using the powerful Jinja template engine.

Create different documents from the same ReST sources (conditional text) Generate document variants from the same ReST sources with Sphinx conditional text.

DITA XML and XSL-FO tutorials DITA XML is a structured authoring language that lets you create documents without worrying about their final appearance on different media. XSL-FO is a language that lets you reorganize and filter XML content and apply a layout to it using a style sheet.

Regular expressions in Python Python's regular expression library helps you manipulate text, especially if you're not familiar with sed or awk.

Automatically insert data into a reStructuredText file Suppose you need to present 3 products, Dianthus, Geum and Prunus, each in three versions 1.0, 1.5 and 2.3.

Automatically insert SQL data into a reStructuredText file We're going to create a database of products with their versions, then format this information in a reStructuredText file.

Shuffling words Like the philosophy master in Molière's Bourgeois gentilhomme, a Python script can easily switch words in a sentence to say the same thing in a more convoluted way.

Managing a project from start to finish It's quite rare, in a professional context, to be able to manage a project from (almost) A to Z, from conception to realization and communication.

The Raspberry Pi 3 as a documentation platform With its modest resources, a Raspberry Pi 3 is all you need to create, manage and generate documentation in PDF, HTML or EPUB format.

sed: modify your text without opening your files Unix clones are rarely used to manage technical documentation.