Login  Register

Re: Recommendations for multi-page and single-page documentation

Posted by LightGuardjp on Apr 16, 2013; 1:40pm
URL: https://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p139.html



On Tue, Apr 16, 2013 at 3:41, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]="mailto:[hidden email]">> wrote:



On Tue, Apr 16, 2013 at 3:28 AM, nawroth [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Sounds nice with the parsing times.

Regarding multi-page output, I want to add that it provides a natural place to add comment threads.

That's exactly what I concluded after taking a walk on this. So I agree, there are use cases when it is needed. It just happens that I remember the many cases when it should not have been used :)
 
The docbook webhelp format is starting to look useful for multi-page output:
http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/ch01.html
You're on a single page but still have an overview of the full document as well as easy access to it (both TOC and search).

A huge improvement. The negative experience of the multi-page HTML is that you lose your place very easily when trying to read straight through. Either that, or you end up only getting a handful of sentences in return for your click...which feels very demotivating. So I'm all about keeping the big picture while still having the granularity to support features like comments. We definitely need to keep innovating in this space.
​I think there's a lot a ways we could try  to solve this. Some fancy JavaScript to keep a bookmark is one idea (perhaps store it in local storage or a cookie), slide out TOC, horizontal scroll (like a physical page turn) and bookmark feature. Certainly ideas to try and see what sticks.