OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] Ajax HTML format wanted

Thanks for this response and anything you can dig up would be welcome.

My question really comes less from matters of styling (and yes, CSS is undoubtedly brilliant) than from information structure and  an interest in how technical audiences (which is my type of audience) use web sites for information.

Rightly or wrongly, they expect to follow a link and get exactly what they need there on (one) screen. They need coherent explanations at different levels, clear organisation and a clear narrative thread (message) at each point. At the same time, without examples, checklists, anecdotes, etc. the text does not have life, is less actionable, and abstract explanations can be hard to penetrate.

DocBook and the web offer a way to have both: the bones on one side and the flesh on another, explanations of terms ready to hand while the context is still on screen, examples you can read if you want, but which don't get in the away.

Web documents can also better the  linear, hierarchical structure of paper, by providing cross cutting views using links - highly valuable to me. And unlike a physical book, you can also have a web book  open at two or more pages  at once. 

Lazy loading of the whole document into the browser is useful too because, once loaded you can flick pages almost as easily as you can with dead trees. IMO it is a bad mistake to underestimate the importance of this if you want to retain your readership.

So, although my question may sound gimmicky, it is really about giving (my) readers what they want i.e. fast and effective access to information and understanding, with everything they need on the desktop in front of them.

Admittedly, this is not addressing accessibility, but it is also not compounding that problem. There's no difficulty outputting different formats for different people/user agents. (Personally, I use hot keys and tabbing extensively and am a reluctant mouse user but, when all said and done, this is pretty unusual these days and, as touch screens get more pervasive, I reckon we'll soon be using our fingers anyway.)

Edwin Aldridge

On 25 April 2013 13:24, David Goss <goss@fstrf.org> wrote:
Personally, I think docbook's HTML output can be very aesthetically pleasing, and so well designed that the sky is the limit with CSS. It's also technologically pleasing, displaying well in my browser of choice (elinks). In my antiquated opinion, web pages are documents, not applications. For our audiences, functionality is more important. Some of the clients we work with are in developing countries and are using very old hardware and slow, unreliable internet access. Even on a fast internet connection, a user can still hit CTRL+F faster than they can scroll around, clicking menus and pecking around to find the "hidden" text they're looking for.

That said, I have experimented specifically with some of the things you're talking about. We tried working in things like thumbnails that float off to the side and expand when clicked, glossary entries that open in fancy-pants popups, etc. One of the most useful things we worked out was implementing the JQuery Lazy Load plugin, which waits to load images until you scroll down to them. It's possible to implement some of these things while still keeping pages accessible, sitting on top of docbook's output and degrading gracefully when the user doesn't want it.

We don't have anything like that in our production documentation though because it breaks the accessibility and easy-of-use. I can dig around and see what I can pull up. There are a lot of possibilities with CSS and JQuery using Docbook, because the DOM in Docbook's output is so well structured.


David Goss, M.A.
Technical Writer, Laboratory Division
Frontier Science & Technology Research Foundation
4033 Maple Road
Amherst, NY 14226
(716) 834-0900 x7218

----- Original Message -----
From: "Edwin Aldridge" <edwin.aldridge@gmail.com>
To: docbook-apps@lists.oasis-open.org
Sent: Thursday, April 25, 2013 5:56:31 AM
Subject: [docbook-apps] Ajax HTML format wanted

I am writing a set of docbook articles which I would like presented on the web but I find the HTML and XHTML formats really clunky. Aesthetics asice, they certainly do not take advantage of the medium's capabilities and am looking for something a bit smarter.

Does anyone know of, or would anyone be interested in developing, stylesheet variant which does something like the following:

* present chapters down one side - just one level, definitely no tree structures dancing before your eyes
* present first level sections as tabs across the top
* present lower level sections as headings (writing to a limit of two levels is a useful discipline)
* present sidebars on the side (like the FO transforms) but say as accordians
* present foot notes and glossary terms as pinable popups onclick or mouseover

This could also make use of the much wider screens now commonly available, e.g. giving lots of display room for sidebars. It would make better use of internal links and non-serial reading approaches (which readers often don#'t do with dead tree media and never do with the web).

There are a few practical challenges - like making the doc display correctly when someone links to an internal URL, but I am sure this is not beyond the wit of someone with good JQuery skills (or similar).

Does anyone know if there is anything out there like that? Or would anyone be interested enough to do something like this?

Edwin Aldridge

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]