There too much effort going towards misunderstanding here. Cancel the question, guys.
On 25 April 2013 17:09, Carlos Araya <carlos.ar...@gmail.com> wrote: > 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.aldri...@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 <g...@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.aldri...@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 >>> >>> >> >
