Re: Online help access question

Subject: Re: Online help access question
From: Helen OBoyle <hoboyle -at- gmail -dot- com>
To: Mark Baker <mbaker -at- analecta -dot- com>
Date: Fri, 30 Sep 2016 09:45:02 +1000


Regarding, "In the end, help systems, KBs, CMSs, and the plain old web are
hypertext systems, and no hypertext system works well if the content it
contains is not actual hypertext"...

I think it's all about what your user community wants. It's necessary to
look at use cases, prioritise them, and then decide on the functionality
the on-line system will offer.

We write in DocBook and publish to Confluence which we use as a
presentation layer, with authentication (the content is proprietary and
restricted to paying customers), limited search, online HTML rendering, and
"give me a Word doc of this subtree" functionality.

In our case, we deliberately TOSSED linking at the presentation layer, for
which metadata was present in the original documentation source files,
because that's what management says our users want, and that contention is
backed up by a small amount of feedback from users.

Our users are largely teams in international subsidiaries, who need to grab
chunks of docs to prove compliance with a piece of an RFP, gain client
consent for implementation of a new feature, document for contract reasons
all enabled functionality in a system as it is delivered, etc. What we've
heard is that users mostly use the Confluence system as an on-demand Word
doc generator for arbitrary chunks of system functionality.

Because we bought the Word doc generator elsewhere, we have no control over
its transforms (or at least, there is an administrative edict to make no
changes to its transforms). It renders any stylised HTML poorly and output
can end up looking like a ransom note with multiple sizes of text, variable
line spacing, etc. The developer of the Word doc generator appears
uninterested in resolving this, or can't resolve this.

It is the opinion of those with access to the web logs (which does not
include me) that people rarely look up content without printing it out, and
therefore the quality of client-facing print rendering must win out over
the desire to provide the most feature-rich online navigation experience.
Any questioning of that is pretty much written off. The doc team also
frequently gets complaints about the quality of the docs based on creative
typography on the part of the Word doc generator when our Confluence pages
include anything other than flat text, moreso than about quality of actual
content. Because of that, we've switched our DocBook -> Confluence Storage
Format transform to render links as flat text.

Users love it, as a more efficient way to get the Word docs they want,
compared to the previous solution of emailing a writer (who might or might
not be on sick leave or annual leave that day) that the user knew had a
PDF->Word converter license, with their Word doc request, and then waiting
for that writer to generate the requested Word doc and mail it back to the
user, who would then edit down the large Word doc to include just the bits
required. (Don't ask. Just. Don't ask. ;-)

Kind regards,

Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Online help access question: From: Suzette Leeming
Re: Online help access question: From: John G
RE: Online help access question: From: Robart, Kay
RE: Online help access question: From: mbaker

Previous by Author: Re: "Age-old" question
Next by Author: rules and expecations / our list
Previous by Thread: inline links (Re: Online help access question)
Next by Thread: Re: Online help access question

What this post helpful? Share it with friends and colleagues:

Sponsored Ads