On the Separation of Authors and Content

Blog entry: Submitted by bnordgren on Wed, 2009-02-25 00:29.

Preface

This is an open letter to the DITA TC regarding something which is in my view a fatal flaw with the design of several DITA elements. The realization crystalized when I was told by someone on the DITA users email list that there is no provision for users to specify captions for their exhibits (figures, tables, etc.) or specify the text of their section headings. In short...<title> doesn't do what intuition says it will do...

"Fixing" DITA so that authors can specify captions and titles and section headings would essentially mean the creation of a parallel DITA grammar which reuses little to nothing.

It's a serious deficiency, but the letter is meant to be somewhat lighthearted. Please consider this a "petition" of sorts and comment on this article to informally sign it. ;)

Liveth By The Golden Rule: Authors Never "Suggest" Text.

For the next release of DITA, please include a suite of well-behaved exhibits with deterministically specifiable captions. Likewise with section and topic headings. As well as an <xref> with deterministic content behavior. You may make a parallel suite of elements or you may change the existing elements, I do not care. But this is the role of the standard and not an extension. If we tried to fix this in an extension we would have to duplicate all the structural elements, starting with topic, then concept, task, and reference. Then content elements section, fig, table, simpletable, etc.

Rationale is as follows:

> In short: a title is not a caption. Or, to be more precise, a caption is
> not a special kind of <title>, so you have to specialize something other
> than <title> if your processing expectations are that precise.
>
> That doesn't mean that DITA's
> wrong and needs to be "fixed". It just means that it's different.

All my objections thus far, particularly the ones which are shared by others on this list, and most especially the ones which have existing, widely used workarounds promulgated by frustrated authors, involve the separation of authors from content.

The text of a caption is content. The text of section headings are content. The text which is substituted by an <xref> into the document is content. These are all my responsibility as author, and I will only delegate the generation of text to a machine (i.e. xref) if the rules by which the machine is governed are crystal clear and universal. Even then the delegation is well constrained.

Separation of content from presentation is admirable and useful. Separation of authors from content results in aggravation and the habitual breaking of arbitrary rules which interfere with productivity. It may well affect adoption, as you absolutely cannot expect DITA to be used to generate scientific publications if you provide no mechanism for authors to write captions or refer to their figures.

If there are scenarios where the display of an exhibit's caption or the title of a section/topic is inappropriate, then you may hide it. But You May Never Change The Words. If the <alt> element were treated similarly, DITA would already be unusable for any US government website. And do not let it ever cross your mind to treat the element like this! You May Never Change The Words. Ever. Authors Never "Suggest" Text.

Content is Mine, Sayeth the Author. Leaving Content in the hands of the tool is what makes DITA broken and is why it must be fixed.

Verily I say Unto You, Deliver Unto the Authors Those Tools Which They Find Pleasing And Which Do Not Put Words Into Their Mouths, and Your Format Will Go Forth Into the World And Multiply.

Bryce

bnordgren's blog
Login to post comments
6160 reads

Hi Bryce,

I am glad you voice your unhappiness about some DITA aspects, your letter expresses hope and love for DITA. Maybe you lack faith in the TC ... Other sceptics just say "DITA no way" or "Forget about DITA" but never start to argue.

I read your open letter but I miss background information to understand your intention. Maybe I just miss "your global" definition of content and title and caption and suggesting text.

You know, I am a learner of English as a foreign language. And the German word Titel can be translated in even more English words like header or heading. Link to dict.leo.org.

For arguments -I learned at school- you should provide reason and example(s) to get to the point and convince.

Here is my rewording of your thesis: "If DITA continues to seperate authors from content then authors will boycott DITA for the rest of there life (or eternity) and DITA will disappear in insignificance." Did I get at least this one right?

Even if I got that I do not know where the seperation happens with DITA. Is it a general XML problem or a problem with topic based authering? Or do you just hate the tags that TC selected for some elements?

I tell everyone that the filename of a topic or map is something different than the title of a topic or map, which is part of the metadata of the contents versus the the filename being part of the URL to locate or link the content. -Not sure if metadata is the opposite of "your" content definition?- I can have many topics with "Introduction" as title, but this would be a conflict if all filenames would be Introduction.xml. Adding a number makes the filename unique - and different from the title. And then we change our policy and rename all introduction topics to "Overview". Renaming all topics and replacing all links in the universe -or- keeping Introduction42.xml as filename of a topic titled "Overview"? This has to be solved by the storage rules and the optional CMS, but it is not a DITA problem. All the metadata should be available for search and retrieval, then wording of filenames gets unimportant.

And yes of course, titles of sections and tables and figures are content, as written in your open letter.

I am not sure if your seperation of author and content is an off-topic regarding DITA? Maybe the DITA Adoption Subcommittee should be addressed to win authors like you for DITA??

-ghk

Gunnar H. Krause, Senior Manager TechDoc, Qimonda AG, Munich

Bryce, I often come back to this posting as a defense, if such is needed, of behaviors that not only DITA but also DocBook, TEI, and other XML authoring vocabularies possess:

Why transformation?

http://lists.xml.org/archives/xml-dev/199809/msg00807.html

To quote,

'The fundamental point is that you cannot predict how your data will be used in the future, so you cannot decide on the "optimal" encoding for it.'

--
Don Day
Chair, OASIS DITA Technical Committee

Don,

Thanks for the link, but the advantages mentioned in the article are why I use DITA!

I fear I was not making my point clearly. There seems to be an argument to be made that <title> is not the same as a figure caption, or a section heading, etc. and separately the text that <xref> injects into my document (usually in the middle of a sentence) is in no way constrained by the standard. My intent was to ask for a closing of these loopholes so that tools are forced to let me specify the section headings, exhibit captions. Now there may have been a bit of a miscommunication in that the envisioned "leeway" turned out to be the application of a "Figure #: <caption text>" template to my supplied caption text. So that part might be resolved.

The parts which remain are:

<xref> is still a wildcard in the middle of my sentences.
<title> should contain any valid text element, including <xref> (my use case is to relate two exhibits together via the captions, e.g. an equation and a table which present related info, attached to the math domain requirements page.)

I see that you would like to try to lock down expected behaviors for elements that create generated text. This is one of those cases where what YOU want to do with the information may be different than what someone else prefers to do with the information. It falls into the "user-preferred styles and run-time options" category of how you want a particular production tool to behave. The DITA Technical Committee has already suggested how these elements can be treated by user agents, but to specify behaviors any further actually becomes a constraint in the specification if it defines the only way a tool can implement an open feature.

If a particular tool were to take your suggestion for template-driven results, I think that would be a Very Good Thing. It might even become a competetive feature helping to enrich the configurability of tools in the marketplace. On the other hand, it would be unfortunate if the specification prevented vendors from being able to satisfy someone else's needs differently than yours.

Given just the simple example of figure references, there are actually a host of configuration options you might want for exhibits:

What template you want to be fulfilled for a reference to a titled fig (exhibit of anything it can contain)
Whether that fig's title should be above or below the exhibit
Whether you want numbering to restart from the chapter, or within the topic if rendered alone
Whether you even want numbering, or prefix
Whether you want titled figures to be collected in a List Of Figures
What title you want for the List Of Figures
Whether you want to allow images or extravagant highlighting in the title to be instanced in any links or in the List Of Figures
Whether you want the author's local text in the link to override the figure's own title
How you want the xref to be styled--do you have preferred coloring or other indication for use of the xref in PDF as opposed to in a Help widget or on a Web page or man page?
Should the link to the figure be reciprocal? What should the behavior be if there are more than one link to the figure?
Should the figure title create automatic indexing of keywords that match a lookup list? What text should be in that list? How do I translate the list so that I get equivalent behavior for my translated documents?
How do I change the prefix text from "Figure" to "Exhibit" in both my xref and in the other places that will use that text (if I opt to use it)? How do I support other language versions of that same prefix text?
Not all pdfs are used online. Some--gasp--are used to actually PRINT books that have no linking behavior, where blue coloring without a page number is meaningless.

This list is not intended to appear detailed to the point of silliness--it is as much as I can recall offhand of a litany of discussions I've had with tools and editor providers, and it hardly scratches the surface.

If your goal is to come up with a simple list of recommended templates for tools providers to consider adopting, that is a worthy goal for discussion. That goal is just not clear from your original note.

While the DITA TC can consider suggesting best practices for implementation, I hope this list shows why a standard must necessarily leave some parts of the specification's usage intentionally open.

--
Don Day
Chair, OASIS DITA Technical Committee

The problem I see with the list above is that it mixes highly specific aspects of particular presentations with generic aspects which should be common to all presentations.

For instance, the color and behavior of a link is highly specific to a particular output target.

On the other hand, the text content of a figure's caption should be constant across all presentations. Whether the figure is numbered and how the figure is numbered should also be constant for all representations of the same map. Concentrating on the things which should be constant across all targets pares the list down substantially.

I do not accept the argument that tools capable of translating text within to various targets are incapable of doing the same thing to the text within <title>.

For <xref>, I do not care to specify linking behavior. <xref> is currently removed and replaced with unconstrained text. The text aspect of <xref> should be constant across all platforms, as the most common usage w.r.t. exhibits is to put <xref> in the middle of a sentence. If the surrounding text does not change, the <xref> text cannot change. We're not even talking about different vendors here, we're talking about translating to different targets from the same software.

There are at least three aspects here and I really only want to regulate one.

Presentation and formatting (I'll call it styling), obviously target specific, obviously not content, supported in some manner by all targets. Authors are offered some basic controls to guide the processing <tt>, and targets are expected to obey this guidance if they can.
Action (i.e. linking behavior), obviously not applicable to a static output format (e.g. postscript, paper, flat text file), but just as obviously native to others (html, etc.) Authors are offered some basic controls ("scope=") and targets are expected to obey if they can.
Content, the meaning destined for human consumption. This should remain unaltered regardless of how it is decorated or how many bells and whistles the target encoding supports. Authors are offered no controls over the few tools which automatically generate text.

It is my contention that the text component of an <xref> substitution is Content and DITA should guarantee it's coherence across targets. Additionally, since it is content, it would be nice for the author to have some basic control over what appears in their document. DITA source files are supposed to be primarily content sans formatting. How ironic that the only category of "processing" to not offer any controls to the author is "content".

I understand what specifications can do. My point is that failure to specify any sort of behavior guarantees non interoperable solutions. Not at the level of presentation, not at the level of what action is taken, but at the level where the sentences may or may not make sense depending on who you send your dita source file to and what tool they happen to use to transform it. You can fix this without shackling the vendors.

Caveat: As indicated on the requirements gathering page, this entire discussion about <xref> should be taken to concern only those <xref> instances with an exhibit as the target. Also, it's very much looking like a predetermined set of templates is a bad idea. A platform-neutral way of coercing all tools to yield the same result is becoming more appealinng.

My comments are censored - why?

-ghk

Gunnar H. Krause, Senior Manager TechDoc, Qimonda AG, Munich

Mine is too, sometimes. The spam filter seems to be set to randomly reject content.

Hi Bryce,

I read your open letter but I miss background information to understand your intention. Maybe I just miss "your global" definition of content and title and caption and suggesting text.

You know, I am a learner of English as a foreign language. And the German word Titel can be translated in even more English words like header or heading. Link to dict.leo.org.

For arguments -I learned at school- you should provide reason and example(s) to get to the point and convince.

And yes of course, titles of sections and tables and figures are content, as written in your open letter.

I am not sure if your seperation of author and content is an off-topic regarding DITA? Maybe the DITA Adoption Subcommittee should be addressed to win authors like you for DITA??

-ghk

Gunnar H. Krause, Senior Manager TechDoc, Qimonda AG, Munich

DITA didn't set out to be a replacement for DocBook, or of a word processor. I don't consider DITA to be useful for writing journal articles (I've tried, but it's not a good fit without a lot of specialization.) If there is a better tool for doing $job, then I say use it. DITA isn't trying to stamp out its competition (assuming there is such a thing).

DITA is also, as its name says, an architecture. It sets a framework for doing topic-based authoring, and that's it. The "standard" specializations of concept, task, reference, bookmap, and so on are no more important than specializations that you make yourself straight from topic or map. A DITA implementation would be conformant if it implemented topic, map and $your_specialization and that's it. It might not be useful, but that's a different matter.

DITA is intended to be usable even outside the domains of paginated print documentation and web pages. If DITA were to define processing expectations then it would necessarily include text-to-speech processors, information management systems and searchable knowledge bases.

I also contend that authors of DITA content "suggest" text all the time, and are fine with it. Seldom do I see authors complaining about the auto-text that DITA-OT sticks in front of <note>s, or the text "Figure 1" that is prepended onto figure captions. The authors that I work with are positively relieved that they don't have to create their own tables of contents, that they can concentrate on writing reference material with consistent machine-generated headings, that cross-references will never be wrong. This trust in the tools didn't come easily, I hasten to add. But the same authors now look back at unstructured FrameMaker and pale in horror at what used to be considered Normal.

Anyone who is interested in nailing down expected DITA processing for a specific narrow domain is welcome to create and contribute a specification, along with whatever specializations are necessary to achieve it. There already are such things; this is where bookmap started, for instance. But it's been my experience that authors who have strict requirements about processing just don't, on the whole, use DITA.

I should remind readers that I am not (any more) a member of the DITA TC. I am just a user who has bought into DITA's worldview.

The benefit of the standardized domains (be they content or structural) is that they enable interoperability. Interoperable text may be ingested by many processors and allows for both free and commercial solutions. Non-interoperable text might not be able to be processed at all by a closed source commercial solution, especially if we re-root the structural tree in "my-special-topic". (BTW-if we were forced to do that, how much of the "framework" would we be using?) In short, I want to be able to send my document to people without also sending my customized processing system. There is indeed something special about the standardized elements.

Also, the benefits of topic re-use, structured (encapsulated) authoring, and multiple targets (xhtml, pdf, etc) apply just as much to journal articles as they do to user's manuals. It's not that there's a One True Tool. DITA has a number of advantages and a number of shortcomings. As does ODF. This is about addressing the shortcomings so that the structured framework is more usable. It is not (yet) about expanding into a new domain, as all of these problems are affecting my current technical documentation efforts.

Prepending "Figure 1" to the provided caption text which is used verbatim is not an example of the author suggesting text, but it is kind of a useless thing to do unless the author can actually cause that figure number to appear in a reference. It seems like a placebo which plays to our expectations (this is how figures are normally annotated) without offering the utility of why we typically annotate things that way. Likewise, presenting a note verbatim with some media-applicable formatting is not "suggesting" text, as no processing system is allowed to alter the content. I would make an argument that if the author needs to, they should be able to refer to a specific note just like they should be able to refer to a specific step or a specific figure, but this leads us back to xref.

There is no way I'd make an argument that constructing a table of contents or the construction of indices is a human's job. But making the choice as to whether and where-in-the-map a particular index/table-of-contents/table-of-figures/table-of-equations occurs is the author's job and should be specifiable in a processing-system-neutral way. The chore of generating these objects may be "processing", but their presense, absense, or location is "content", not processing. When the only thing considered is the "table of contents", it is easy to talk yourself into believing that this table manifests itself differently in different media and that it should be left up to the processing system. But when the concept is generalized to other kinds of automatically generated tables and indices, an author's guidance is required to inform the processing system what should be included, what shouldn't, and how the items should be arranged. Then, all processing systems should comply with the author's wishes within the ability of the media to represent those wishes. Fortunately, these objects are well defined and have simple controls.

I do understand that DITA should be usable outside of the print domain. I just do not consider the notion of a "table of equations" or a figure caption to be a print-only/web-only construct.

Why not use the <desc/> element from within <fig/>?

From the DITA tag reference:

<fig><title>The Handshake</title> <desc>This image shows two hands clasped in a formal, business-like handshake.</desc> <image href="handshake.jpg" alt="The Handshake"/> </fig>

I don't get your point.