Specs and Docs

A modern publishing workflow for your product literature

Bypass the Madness!

Your product literature publishing workflow may have just too many expensive pitstops. Let’s see if we can help.
Old-school product literature publishing:
The traditional, PDF-based publishing workflow outlined below was established about forty years ago and is still used by many brands: A document is created by a writer, then formatted by a designer, then “rendered” as a PDF and uploaded to a web server.

In this workflow, each document is an island with its own resources, and the same applies to translations. Keeping documents in sync requires complex workflows and dedicated tools.		 LOOPS / Specs and Docs:
Our single source publishing workflow uses the web’s full potential instead of relying on PDFs:

Content is formatted using a lightweight markup language, then converted to beautiful, responsive web (HTML) documents that can easily be translated by humans or machine translation engines.

Whatever web-ready content you have can be used in this workflow, and web manuals can also be referenced and integrated into your other online offerings.
1. Writing Illustration
Old-school:
Software: Usually Microsoft Word. Documents are a hodgepodge of content; purely visual formatting, structural information, embedded images and fonts. In a word: a mess.		 LOOPS / Specs and Docs:
Markdown, the lingua franca of GitHub and thousands of other platforms. Structural markup is minimal and easy to learn and read. Any tool on any platform can be used; no licenses are required. Images are linked local files or public URLs. And if errors are found after publishing, they can be easily fixed in the Markdown source files without the need for a graphic designer.
Illustration 2. Typesetting
Old-school:
Software: usually Adobe InDesign. Microsoft Word documents from technical writers are imported and often “adapted” (often a fight with byzantine and conflicting markup rules) or completely reformatted/rebuilt.

This is a time-consuming process, where a graphic designer – who may or may not understand the product and its documentation – has to make sense of what he has been given.		 LOOPS / Specs and Docs:
There is no ”real” design process. The structural markup (heading, lists etc.) is already there. Content is placed in a standard template and automatically linked to a style sheet. It usually “just works” and looks great.
3. Fonts / Typography
Old-school:
The company’s fonts (usually licensed and in proprietary formats) need to be available on the machine where content is typeset. External translation workflows may also require these fonts.		 LOOPS / Specs and Docs:
The company’s web fonts are linked to the HTML templates once. After that, every newly rendered document automatically uses the proper web fonts. Free and open source font repositories such as Google Fonts can be used, including the Google Noto Sans family covering thousands of alphabets.
Illustration 4. Working with metadata
Old-school:
If there is metadata (structured information about the product or document that may or may not go into the final document), that metadata needs to be stored and forwarded outside of the actual document (or document set) through e-mails, “sidecar” text files etc.

These “meta” files can get lost along the way, leading to delays and possibly errors.		 LOOPS / Specs and Docs:
Metadata such as date, author and document type can be added to the document header in a simple, standardized format called YAML. Metadata can be seen and updated by everyone and incorporated in the actual document through the template. New metadata fields can easily be added and used in the template.
5. Translation Illustration
Old-school:
In traditional workflows, translators need to have the software (usually InDesign) and assets (fonts, illustrations) that were used to create the translation source. They will then overwrite the original content with their translations and return files that the graphic design department to review, adjust, concatenate and publish. In modern workflows, intermediate files (for example IDML for Adobe InDesign) are created and then parsed by translation software that will isolate translatable content. The IDML files are then re-imported and saved by the graphic designer. This all usually works, but it is a fairly complex and time-consuming process.		 LOOPS / Specs and Docs:
Markdown files are text files and can be translated directly in any text editor. They can even be processed as such in machine translation tools with a web interface (such as DeepL or Google Translate), which will usually retain markup for headings, lists, hyperlinks etc., requiring only small adjustments. Alternatively, professional translation management systems such as Phrase can process Markdown files and separate translatable content, tags and metadata. Brands can choose to publish machine translations, post-edited machine translations or human translations.
Illustration 6. Publishing
Old-school:
Typeset documents are rendered from the design application, typically as PDFs. These PDFs are then forwarded to the web design team for upload to the server, where they need to be added to a file manager or linked from a web page.

If errors are found in a published document, they need to be fixed “upstream” by the author or designer, and the documents need to be exported as PDFs and re-uploaded to the server again – a multi-step process that will often cause delays.		 LOOPS / Specs and Docs:
Documents are valid HTML and can be accessed as such using any web browser. They are immediately available to human readers and as valid, well-structured “search engine fodder”.

For content hosted on the Specs and Docs site, a Markdown file can be converted to HTML in seconds, because our conversion engine LOOPS is installed on site, acting as a static site generator.

If a brand or their target audience requires PDFs, they can easily be created from the rendered HTML files; both server-side using a commercial PDF renderer or by consumers (using the “Save as PDF” feature available in every modern browser).
7. Updates Illustration
Old-school:
When a brand introduces new corporate design elements or content such as boilerplate text changes, updating legacy documentation usually requires significant effort. In fact, management may decide that it’s not worth the cost and effort, leaving outdated versions of documents online, which reflects poorly on the brand image.		 LOOPS / Specs and Docs:
In the Specs and Docs workflow, content and design are completely separated, much as in a content management system.

Design changes can be implemented by modifying the style sheet or simply replacing a logo or illustration.

Structural changes (such as adding a new header, footer or sidebar) can be implemented by updating the HTML template and re-rendering all HTML files.

Even for large (hundreds or thousands) document sets, updates typically take less than a minute.

Investing in a modern documentation publishing format and workflow will lay the groundwork for many years to come. We are ready to streamline your brand’s product literature for the 21st century.

Let’s talk!

↻ 2025-02-21