Modern approach to technical writing
There is a wide range of technical writing tools available on today’s market.
There are systems for simple tasks that do not involve processing of large content volumes. A user guide for a small article, such as a wristwatch, or a simple computer program, such as an English-Spanish dictionary, can serve as an example. In these cases, one of the well-known editors (Adobe PageMaker, Adobe InDesign, and the most common among those Microsoft Word) will suit the goal. The final result is usually a PDF file for distribution together with the product.
However, when there is a wide range of production, customization becomes unavoidable: each modification of an article, each release of a computer program – all this multiplies the content volumes to be processed. As a result, more time and money is required.
To make the task simpler, more sophisticated means of content management were invented. The SCHEMA ST4 system is one of most prominent examples – the architect supervises the creation and support of documentation templates, and the technical writer controls the content itself. ST4 allows for segmenting so that you can assign specific metadata to each segment of the content to have it automatically included into the documentation for the relevant products.
It is the architects who develop templates. Textual content and graphics are created by technical writers and graphic designers. The system allows exporting the final content into various formats – for example, you can export to PDF, Microsoft Word, and HTML5 that have already gained much popularity. Having documentation in the HTML5 format, you can quickly find the required information by using keywords or the table of contents. To view a document in the HTML5 format, a conventional web browser, such as Google Chrome or Microsoft Edge, can be used.
A special interface is designed to send the documentation to translation. When the translation is done, the translator exports the translated content back into ST4. The completeness of the project’s translation in general and that of its nodes in particular is shown by the translation status indicator. All this simplifies documentation’s localization, along with its translation into other languages. There is no need to manually collect dispersed files, since all the necessary information nodes are collected automatically within the system. The technical writer only needs to use the necessary commands in the graphical interface of the ST4 system in order to send the project for translation. Though in most cases the project is initially sent to the translator just to find out the translation’s cost. Then a decision will be made whether to proceed with the translation or not.
For direct editing of the documentation text, the XMetaL editor is used, which is compatible with the ST4 system. It is meant for documents that are based on an XML-like structure and allows you to edit the content both in WYSIWYG mode and in tag markup mode. Using the latter, the author can see which tag is used for the document portion in question. The program’s ability to switch to the XML editing mode assures the most accurate work. However, according to common practice, working in XML editing mode is usually not part of everyday routine. Illustration files can be in the Adobe Illustrator, PDF, EPS, or PNG formats. They can be linked to the project and used in the documentation.
Documentation templates, created beforehand, do save you time when formatting typical documentation items. You only need to pick up a documentation template from those prepared beforehand, in accord with the documentation topic required, and then link particular documentation nodes to it. Each node represents a minimum independent documentation segment. For example, it can be a disclaimer or a subsection describing some menu command or interface’s part of a computer program or hardware device. Header and footer are formatted automatically in accord with the template set by the architect. The technical writer just needs to key in the text and set the markup. Text portions can be marked up as GUI items, as file names, as subsections within sections, etc. Plain text does not require any markup.
The system provides for version control for individual nodes and for the entire project. Each time a project is approved for publication, a new version is automatically created. Likewise, a new version is automatically created when you begin to edit any documentation node that has already been approved for publication.
The ST4 system features a detailed Help made in the HTML5 format with information about any option or command. It is possible to use scripts to automate routine processes; and there is an extensive taxonomic system available. For example, you can assign attributes to certain documentation nodes indicating particular product versions to which they pertain, as well as you can insert your comments directly in the text and also in metadata. Comments are not included in the resulting text that is published.
On finishing his or her work on a set of nodes, the technical writer can mark the nodes as “released” and send them to his or her supervisor for verification. Later on, when the content is considered as final, the nodes should be marked as “approved”. They can then be incorporated into the project and sent to translators for localization. If no translation is required, you can immediately publish the output on the website in a specified format: HTML5, PDF, or Microsoft Word.
Modern-day systems for creating technical documentation, such as SCHEMA ST4, offer much more capabilities than the conventional desktop publishing systems. Having a wider range of functions, they make it easier to work with documentation in large quantities. They save you time and money.
