Specs and Docs ⋅ Our Process

“So – how does this work?”

We are looking forward to turning your traditional manuals into responsive, translation-ready web manuals. Let us walk you through our process.

1. Project Scope Definition

In the first project phase, we will analyze the scope of the project. Topics we’ll discuss with you:

• How many product ranges and products does your company offer?
• What kind of product documentation do you make available (quick guides, full manuals, software update information…)?
• What applications and document formats do you use to create content (Adobe InDesign, Microsoft Word …)?
• Can you make all documentation and illustrations that you want to convert to web-ready documents available in open (editable) formats?

2. Ingest / Document conversion

1. Documents should be made available via a file transfer or sharing system such as WeTransfer or Dropbox, either as an interactive share or a one-time file delivery.
2. We will analyze documents based on a variety of criteria, such as

• data format
• completeness (documents, linked assets such as illustrations, special fonts…)
• internal structure (use of paragraph and character styles)
• language – style and complexity, grammar (complete sentences versus fragments), use of passive voice, etc.

In general, the best results can only be achieved with sources in open (editable) files, for example, Microsoft Word or Adobe InDesign documents / packages. Converting PDFs requires far more effort, as PDF is a page-based, non-semantic format, and extracting content requires considerable effort, especially with complex, multi-column layouts and many embedded illustrations.

3. Quote

1. We will give you a quote for processing and conversion of your documents.
2. You may want to do a smaller test project before committing to a full conversion of all your documents. In that case, please note that non-trivial base efforts will be required to set up the project and workflow. Accordingly, please expect higher upfront costs or more rudimentary results (no customization of project configuration or styles), depending on our specific agreement.
3. When you have confirmed the quote, we’ll get going.

4. Content export and conversion

1. Textual content (copy) from your source documents is exported from the native applications or PDFs to an intermediate format; a kind of “raw text” or “raw Markdown” that may still contain unnecessary formatting, tags, etc. Details vary depending on your source files’ format, structure, and complexity. We will utilize every available technology to expedite and automate the process, but often, the devil is in the details.
2. Illustrations are exported from the source documents (if they are embedded) or converted to a web-ready format if they are available as linked binary assets (proprietary formats such as Adobe Illustrator or Photoshop).
3. Content will be cleaned up. We will analyze issues and try to apply catch-all solutions (project-wide search and replace) instead of fixing issues individually.

5. Templating and Styling

1. We will analyze your documents’ styling / presentation – fonts; paragraph and character styles; use of corporate colors etc. If you have a corporate design guide, please make it available to us. It will also be helpful if we have access to your designer or design agency.
2. We will rebuild these styles, with a highly flexible general-purpose style sheet set as the starting point. All adaptations required for your brand are defined as “overrides” in a brand-specific style sheet.
3. Boilerplate template elements are populated with information that should be presented on every page, such as navigation bars and footers with copyright information and external links.

6. Project Configuration

1. We will define metadata files that hold central information applicable to all your manuals and other content: brand name, address, contact data, brand home page, and social media URLs, etc. These are variables that can be used in templates and documents.
2. We will set up so-called default files that govern how exactly the Markdown-formatted sources are converted to the target format (usually HTML). This is where it all comes together: content, target format specifications, style sheets, illustrations, metadata, and processing instructions.

7. Test runs

1. We will process source documents and check the resulting (rendered) documents for errors (structure, image, and style sheet paths, heading hierarchy, variable placement, etc). Issues will be fixed “upstream”, i.e., by correcting source documents and configuration files.

8. Content optimization

1. At this point, the web manuals should reflect the content and structure of the original documentation. We will present and discuss the results with you.
2. In the next step, we will review and edit the Markdown-formatted content to ensure it is translation-friendly. Depending on the quality and scope of the source content, this can be quick or a complex and time-consuming process. Again, we will try to fix issues with sweeping search and replace patterns and other techniques – but as this is a proofreading and editing process, it will usually take more time than purely technical and structural issues.

The result will be a set of English manuals that are ready for rendering and translation.

9. Upload to LOOPS Server, Access Configuration

• Finished English documents are uploaded to the LOOPS server. This is essentially a basic web server with a file manager, attached to multiple conversion and translation engines. File names and content can be changed after upload; a visual editor is available.

10. Translation

There are multiple options for translation. Currently, we support these workflows:

1. Documents can be sent to a separate, full-scale translation management system or CAT editor for translation by professional human translators, and finished translations can be uploaded as such to LOOPS.
2. Markdown documents can be sent to ChatGPT, which is instructed (prompted) to translate content and return translated documents. This is a chunk-based translation model, where tone of voice and terminology are kept intact.
3. HTML documents can be sent to DeepL and will be translated in full, with all HTML formatting intact. This is the classical segment-based neural machine translation approach, with high-quality results, but it may also lead to “slips” and inconsistencies that result from a lack of context. For example, a simple / short caption or heading such as “Note” or “Table” may be mistranslated because the machine translation engine does not consider context. We try to avoid these pitfalls by ensuring that your content is translation-friendly, but no machine translation will give perfect results.

11. Account handover

• Once all required translations have been created, we will give you access to the Specs and Docs account created for you. From this point on, you will be able to edit, rename, delete, update, and save both original documents and translations as required.

12. Conversion, Export, and Publishing

The internal Specs and Docs document format is Markdown. For publishing, you will want to create the proper target format. This is usually HTML, and by default, all our accounts and projects are configured accordingly.

• For conversion, simply select documents (for example, only new or all documents) and click “Convert”. That’s it. Everything else is done server-side based on the project configuration.
• A few seconds later, you can pick up your rendered documents in the “Output” section of the interface.
• For publishing in your own content management system, select all documents and click “Download”.
• For publishing in your Specs and Docs site / subdomain, click “Publish to Specs and Docs”.

12. Iterations

• If an (English) source document needs to be updated, your writer can directly edit the document.
• If you want a human translator to update a translation, they can directly edit the translation.
• If you want to use a machine translation engine to update a translation, and if you have a translation license, select the respective source documents and click “Translate”. This will automatically overwrite the existing translation.
• If you want to use a machine translation engine to update a translation, and if you have no translation license, send us a translation request, and we will update the documents for you.

↻ 2025-08-21