Re: [docbook-apps] Ajax HTML format wanted

[Carlos Araya <carlos.araya@gmail.com>]

Edwin,

It is all in how the document is structured.  I've built very technical documents for audiences like yours using Docbook and the feedback has been consistently positive.  You can add a lot of the functionality you want without having to change the way that the stock stylesheets handle the HTML content, you just have to write mode Docbook, CSS and _javascript_ to make sure that the behaviors happen the way you want them 


More specific answers are provides inline

On Thu, Apr 25, 2013 at 8:13 AM, Edwin Aldridge <edwin.aldridge@gmail.com> wrote:

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.

What is stopping you from using example tags(http://docbook.org/tdg51/en/html/example.html) or program listings with callouts (http://docbook.org/tdg51/en/html/programlistingco.html)  for examples depending in your audience?   Can you script the examples so that they'll provide the level of interactivity you want?

You can make the text as rich as you want, it takes more work but the result is worth it in the end.

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.

You can create a glossary with links to and from the glossary entry; the link element, along with xml:id would allow you to do something similar to what you want (http://docbook.org/tdg51/en/html/link.html)

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. 

See my point above for building links within a document.

From learning (or just a reading) point of view, why would you have a document open more than the place you're reading? Even reference books work best when you're using one specific portion of the document. You may jump back and forth but not at the same time.   

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.

Navigate using hyperlinks or if it's really important use a variant of the webhelp customization to do what you are looking for. If none of those options work you can build your own extensions and then present them back to the community for possible inclusion in the style sheet distribution.

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.

At least from my point of view it's not that your position is gimmicky. I do wonder if you've explored what the stock stylesheets (with or without customizations) can do. 

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.)

Until that happens you are still dealing with a predominantly keyboard-based  user base.  What percentage of your users are currently using touch screen devices? How many of those users are using devices like screen readers or other devices to assist with disabilities? How would your proposed changes impact their access to your content?

Carlos

Regards

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



---
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?


Regards
Edwin Aldridge