Single-sourcing and granularity

[PaoloT]

Hi,

One of the main topics in technical documentation is single-sourcing. This means that from a single matrix you get an Online Help, a PDF file, a printed book, and an eBook.

There are two different workflows: (a) starting from a big, traditional document as the matrix, or (b) starting from small XML files, that will then be collated into a bigger book.

The advantage of solution (a) may be in being able to work in a traditional way, and focus more on the page layout.

The advantage of solution (b) is granularity, and ease of reuse. If one has to publish a reduced set of instructions, unchecking some of the XML files from the edition is easy.

FrameMaker and MadCap Flare try to mix the two approaches. FrameMaker has also the option to be used as a traditional solution, as in (a).

Publisher is currently in the same category of InDesign, and is apparently aiming at (a). My high hope is that Serif can find a way to "modernize" its approach, and go into the territories of (b).

InDesign is incredibly weak in managing granularity. You get a book and its documents, and that's all. The added Structure pane is so hard to use, that is unusable.

Publisher has a wonderfully navigable ToC pane, that makes me hope it will be extended when a multi-document Book functionality will be available, to integrate both the separate documents and the internal sections.

This would allow for working with smaller documents. With this level of granularity, a single chapter may be easily split into as many documents as there are sections. Even one-page documents. Navigating among them will be easy in the ToC/Structure pane.

If a different edition is needed, one can just create a new Book, and add, rearrange or remove anything.

The ideal model is Scrivener, the wonderful British idea-processor that (together with Ulysses) revolutionized the world of writing tools, then dominated by Word (in the same way InDesign is still dominating, with its leaden gravity, the publishing area).

Paolo

 

[Ramon56]

In technical documentation, there is actually an international specification for the production of technical publications: S1000D, “International specification for technical publications using a common source database”. It has been around since 1989 and is regularly updated. It is based on XML and mainly used in aerospace and major products such as ships or complex equipment. However, they have actually documented an example using a bycicle, so as to show that it should not be used "only" for complicated equipment or products. Most major defense departments in the world (MoDs) currently demand that their technical publications are delivered in S1000D format.

In case that you are interested, you can get it (for free) at http://www.s1000d.org.

Additionally, there are some associated guidelines on how to actually write technical documentation, namely STE-100, "Simplified Technical English". You can get this (also for free) from https://asd-ste100.org/

There are tools out there that allow to define data modules in accordance with S1000D, and the generate the publication. The interesting thing about the data module concept is that you can assemble the publication from the different data modules, and reuse a same data module (such as warnings, or how to open a panel) multiple times in a same document. This is the (b) concept that you outline. And yes, you can generate the S1000D database, an IETP (interactive electronic technical publication), the PDF or the book from the same sopurce.

However, I do not see Affinity to build in this capability in Publisher, though I think it would a nice feature, as it greatly expands its flexibility. If they DO address this capability, they should certainly allow to export these kinds of "books" in S1000D and IETP formats, as that would be greatly appreciated by small and medium companies that develop S1000D information but have to pay for far more expensive tools.

[fde101]

36 minutes ago, Ramon56 said:

If they DO address this capability, they should certainly allow to export these kinds of "books" in S1000D and IETP formats

From what you are describing, I would think it would be a better fit for a tool like Scrivener to incorporate the creation of these formats.  Importing these formats, possibly via an extension to the mail merge feature, would likely be a better fit for Publisher.

[PaoloT]

2 hours ago, Ramon56 said:

In technical documentation, there is actually an international specification for the production of technical publications: S1000D, “International specification for technical publications using a common source database”.

Well, there are actually several "standards" for technical documentation. None of them is, as usual with standards, the universally adopted one. (Maybe we need a new standard to standardize all of them… – oh, they have tried, and then amended it with a new universal standard…).

One of the best known and widely adopted set of specifications is probably DITA, first created by IBM and in use in the public administration. DocBook has been another widely adopted XML schema for technical documentation. GitBook is a modern way of structuring content for documentation in a dedicated and widespread online documentation system.

All of these systems are focusing on granularity. Smaller pieces of documentation, structured in a coherent way, are easier to write, proofread, revise, maintain and reuse than a long, unstructured document. This granularity is not only useful for technical documentation, but also for scientific papers, and for any reference publication (like a cookbook or a textbook).

FrameMaker is capable of working in either way: free-form, or structured. If working in a structured way, the document will adhere to an XML schema to which all grains will adhere. (It's really sad to see in which hostile thing Adobe was able to transform this wonderful piece of creativity in technology…).

1 hour ago, fde101 said:

I would think it would be a better fit for a tool like Scrivener to incorporate the creation of these formats.

Scrivener is a fantastic concept, and a great realization for its aim: a drafting program, leading you up to the stage before the final formatting. It can't deal with graphic formats needed for high-quality printing, and can't deal with linked resources in a linear way. In other words, it's missing the page layout features that are not in its scope.

Modern technical manuals, cookbooks, school textbooks, reports, require the advanced page layout features that are typical of Publisher. Great examples of this type of publication are Serif's own workbooks: clear and concise instructions, blended with great page design and illustrations. Manuals are no longer intended as grey and boring sequences of text; they are a joined effort between a text and a visual layer of communication.

A tool like this is currently missing. FrameMaker has been destroyed. MadCap Flare has never been developed with advanced page layout in mind. InDesign is a great page layout program, with no real structuring capabilities. I really hope Publisher will be this (no longer) missing tool.

Paolo

 

[Ramon56]

1 hour ago, PaoloT said:

Well, there are actually several "standards" for technical documentation. None of them is, as usual with standards, the universally adopted one. (Maybe we need a new standard to standardize all of them… – oh, they have tried, and then amended it with a new universal standard…).

One of the best known and widely adopted set of specifications is probably DITA, first created by IBM and in use in the public administration. DocBook has been another widely adopted XML schema for technical documentation. GitBook is a modern way of structuring content for documentation in a dedicated and widespread online documentation system.

Yes, I am aware of them, but ultimately these are proprietary standards developed by a single company. S1000D is an international specification which is publicly available and is developed jointly by three standarization organisations representing both US and European industries that employ together almost 3.000.000 people. It is therefore a powerhouse amongst standards.

1 hour ago, PaoloT said:

Scrivener is a fantastic concept, and a great realization for its aim: a drafting program, leading you up to the stage before the final formatting. It can't deal with graphic formats needed for high-quality printing, and can't deal with linked resources in a linear way. In other words, it's missing the page layout features that are not in its scope.

Modern technical manuals, cookbooks, school textbooks, reports, require the advanced page layout features that are typical of Publisher. Great examples of this type of publication are Serif's own workbooks: clear and concise instructions, blended with great page design and illustrations. Manuals are no longer intended as grey and boring sequences of text; they are a joined effort between a text and a visual layer of communication.

Having used Scrivener myself, I must fully agree. But I like a lot its modular capability, in order to manage separate files. PagePlus had also that capability, though more limited than Scrivener. If Publisher can add the main features of Scrivener, such as modular use, ePub export, etc, it would really become the standard for those tasks.

[PaoloT]

16 minutes ago, Ramon56 said:

If Publisher can add the main features of Scrivener, such as modular use, ePub export, etc, it would really become the standard for those tasks.

I fully agree!

Paolo

 

[Old Bruce]

For this to work Serif Affinity would need to add Linked Text Documents. Whole new can of worms.

[Ramon56]

12 minutes ago, Old Bruce said:

For this to work Serif Affinity would need to add Linked Text Documents. Whole new can of worms.

Agreed. But PagePlus did have a limited capability to do this. On one side, you had the PagePlus documents, and then you had the PagePlus books (see example from one of my books below). They were two different types of files. The PagePlus document would be equivalent to the S1000D data module, the Pageplus book would be the S1000D publication module. They need not to be mixed, as Scriverner does, but it's much easier to implement.

This PagePlus feature would probably not be sufficient to handle the S1000D documents, but it certainly would cover the Scrivener equivalent. You could improve it by "linking" the individual files to the Publisher sections.

[PaoloT]

4 hours ago, Old Bruce said:

For this to work Serif Affinity would need to add Linked Text Documents.

If you are referring to my proposal – no, it wouldn't have nothing to do with it.

Single 'grains' wouldn't have to be imported in a document. They would have to be added to a Book, Folder, Binder, Collection, or whatever it is called in programs managing projects made of separate pieces of text.

If you are familiar with Scrivener (the light side of 'granular' writing – I will not point you to Oxygen, that is the dark side…), what it does is letting you write short pieces of texts. These will appear as a continual document, when joined together with all the other short pieces of text, in a full project called the Binder.

Ulysses calls each of the small pieces of text 'sheets'. They are joined together in a Group.

InDesign has a rough version of this concept with the Book. You can only deal with a single level in the book's hierarchy, so it is not good for 'granular' development.

Publisher can already deal with hierarchical sections. Only, the separate sections are all contained in a single document. You can't turn them on/off when producing the final document. You can't have multiple authors work on them. You can't reuse them in other projects, without physically copying & pasting them.

Paolo

 

[sfriedberg]

@PaoloT, I think you just described what @Old Bruce called "linked text documents"!

[PaoloT]

2 hours ago, sfriedberg said:

@PaoloT, I think you just described what @Old Bruce called "linked text documents"!

I'm probably thinking in Adobe terms. InDesign calls "links" any object that is imported in a document. Publisher calls them "referenced files". Scrivener joins together whole RTF documents, that are bonded together. There is no import/linking/referencing in this case.

Paolo