Source format
Word processors have unaccustomed us to distinguishing between form and content. But confusing the two leads to many errors and wasted time.
Definition
Section titled “Definition”The content of a technical writing project is created in a Source formatThe format content is authored in, as distinct from the target format it's published to — the recipe versus the dish.View in glossary →, distinct from the format of the deliverables, or the target format. To use an analogy often found in software development, the source format is the recipe, while the Target formatThe format a reader actually consumes — PDF, HTML, compiled help — generated from the source format.View in glossary → is the dish. In photography, the source format is the RAW format produced by the camera, preferred by professional photographers for retouching, and the target format is the JPEG format.
Why it matters
Section titled “Why it matters”Word processors have moved us away from distinguishing between form and content. However, confusing the two leads to numerous errors and wasted time.
Key principles
Section titled “Key principles”The document presented to the user comprises two fundamental aspects:
- Content
- Layout
During the development of technical documentation, these two aspects must be clearly distinguished and can be managed by different individuals:
- The technical writer
- The graphic designer
When layout is as essential as content, or when it needs to be varied, as in a sales brochure, writing and layout are performed using separate tools:
- Text editor
- Desktop publishing (DTP) software like InDesign or Scribus
When layout is less critical than content, or when it needs to be consistent, as in technical documentation, editing and layout are performed in:
| File type | Example |
|---|---|
| The same files | For example, FrameMaker files. |
| Different files | For example, XML content files and an XSLT (XSL Transformations)A language for transforming XML documents into other XML, HTML, or text documents. XML publishing chains such as the DITA Open Toolkit use XSLT stylesheets to produce HTML, or XSL-FO for PDF output.View in glossary → stylesheet. |
In a FrameMaker file, the separation between content and form is significant, though not complete: content and layout reside in the same file. FrameMaker applies a consistent page layout to an entire file but allows manual addition of layout elements. The same layout can be duplicated for the entire document, or different layouts can be used for each file comprising the document.
Source formats: modularity, format, and semantic structuring.
Source formats can be classified by their degree of modularity, file format, and semantic structuring.
Structured XML formats such as DocBookA semantic XML markup language for technical documentation, organized in books, chapters, and sections rather than typed topics. It predates DITA XML and is the usual point of comparison when choosing a structured format.View in glossary → and DITA XML apply a uniform page layout to an entire document and do not permit the manual addition of layout elements or the application of different layouts to the various files that comprise the document.
| Format | Manual layout options |
|---|---|
| MS Word | Yes |
| FrameMaker | Yes |
| DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → | No |
When content and layout are closely intertwined, as in a word processor, modifying the content without disrupting the layout is challenging. Consequently, each time a new version of technical documentation is published, the technical writing team spends long hours correcting layout errors generated by the software. This issue is less prevalent with FrameMaker but remains significant. It is nonexistent with DITA XML and DocBook (the only errors that can occur are compilation errors due to incorrect XML syntax; these are easily corrected).
Technical documentation source files are in:
- Binary or
- Text format
This format is also:
- WYSIWYGShort for what you see is what you get: editing in a view that looks like the final page, as in a word processor, with layout applied by hand. Its opposite is structured authoring, where writers mark up meaning and layout is applied automatically at publication.View in glossary → or
- Structured
Finally, this format is:
- Modular or
- Monolithic
This last aspect determines how the format handles Single-sourcingGenerating multiple deliverables (PDF, HTML, help formats) from one source, rather than maintaining a separate source per output format.View in glossary →:
- According to a book-to-online-help logic or
- Online-help-to-book
In a book-to-online-help logic, you author a comprehensive linear document first and derive individual help TopicThe smallest autonomous, titled unit of information in DITA XML, typed as concept, task, or reference and assembled into documents via ditamaps.View in glossary → from it afterward; in an online-help-to-book logic, you author atomic, standalone topics first and assemble them into a book-like document when needed. Monolithic formats naturally suit the former, while modular formats naturally suit the latter.
Independently of layout control, formats also differ in whether they are semantically structured - whether the markup encodes meaning rather than appearance, as shown in the radar chart above.
FrameMaker and DocBook are not entirely modular, as the smallest information units that can be manipulated are not generic: they contain elements such as table of contents structure or cross-references that are only valid in limited contexts.
Monolithic or modular documents
Section titled “Monolithic or modular documents”The source format can be based on either monolithic files or clusters of modular files.
Monolithic files (e.g., MS Word, LibreOffice, or FrameMaker) centralize all content in a single, easily manageable file, but limit content sharing; this increases the risk of inconsistent or duplicate information.
Monolithic technical writing source format
Clusters of modular files (e.g., DITA XML) aggregate the content of multiple files, facilitating content sharing and reuse. This approach is challenging to implement company-wide but should be standard for a technical writing team.
Modular technical writing source format
Some word processors can handle modular documents, though not effectively. Conversely, a DocBook or DITA XML document can be monolithic, but then loses its flexibility.
Markdown as a source format
Section titled “Markdown as a source format”A modern source format widely used in technical writing is MarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary →. It is a lightweight, human-readable text format that clearly separates content from formatting.
For instance:
- Headings are indicated by
#, not by visual styles. - Lists are marked with
-or*, not graphic bullets. - Bold or italic text is framed by
**or_.
Markdown offers several advantages for technical writing:
- Simplicity: Easy to learn and use.
- Modularity: Each Markdown file can stand alone as an information module.
- Interoperability: Text files can be converted to HTML, PDF, DocBook, DITA, or even Word, thanks to generators like Pandoc.
- Traceability: As the files are plain text, they are ideally suited for versioning with Git or other source control systems.
Markdown enables the creation of structured, reusable content while remaining simple and accessible to technical writers. It bridges conventional word processing (WYSIWYG, but not very modular or structured) and XML (modular and structured, but complex to manipulate).
What is an information module?
Section titled “What is an information module?”The world’s most recognized modular system is undoubtedly Lego bricks. Adapted to technical documentation, the module principle improves the quality of technical manuals and the productivity of technical writers.
However, is it sufficient to convert FrameMaker documentation to a structured format like DITA XML or Markdown to achieve Modular documentationContent built from small, reusable, standalone units (topics or modules) assembled on demand, rather than authored as monolithic documents.View in glossary →? Unfortunately, no. If the original content mixes various types of information (concepts, step-by-step procedures, references), you can convert it to Markdown or DITA XML without strictly adhering to the format’s semantics.
Nonetheless, if your document ends up being based on files corresponding to different schemas (concept, task, or reference), it doesn’t necessarily result in truly modular documentation. Indeed, if a document contains only files of a single type, it risks being incomplete and incoherent.
This documentation is not modular, as it lacks genuine information modules. A module is a complete and coherent atomic element reusable in different contexts. If the original monolithic document is merely split into numerous files, information modules haven’t been created yet. The next step is to rewrite each file (using the minimalist approach, for example) to make it more generic and a genuine module.
It’s crucial to adopt a structural approach and decide on each module’s content from the perspective of the overall document architecture. Similarly, references like “See next section” should be replaced by cross-references. Ideally, these cross-references should not be located in the content files themselves but in a relative section specific to each DitamapAn external table-of-contents file that assembles DITA XML topics into a document, without the topics themselves needing to know their position in that document.View in glossary → file.
In this way, modules are perfectly decontextualized, and structural information such as cross-references is placed in files without textual content.
Binary or text files
Section titled “Binary or text files”Source formats can be binary or text.
- Binary formats are opaque: if opened with a text editor like Notepad, they display a string of hieroglyphic characters and can typically only be modified with specific software.
- Text formats are transparent: if opened with a text editor, they show text and tags, allowing them to be modified with various software, easily manipulated via batch processes on the command line without even opening them, and lend themselves to powerful regular expressions.
Markdown exemplifies a transparent, simple, modular, and easily traceable text format - ideal for managing content in a version control system alongside other project assets.
Related articles
Section titled “Related articles”Related reading
Section titled “Related reading”- Why hand-maintained InDesign files rot - and what docs-as-code does instead - how the source format shapes the whole production chain.
- Turn Word files into SEO-optimized web pages: boost your content reach with AI - converting a closed source format into web-ready content.