Posted by
nawroth on
Oct 12, 2013; 1:36am
URL: https://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p795.html
Oops, a super late reply from me here:
2013/4/16 lightguard.jp [via Asciidoctor :: Discussion]
<
[hidden email]>:
>>>
>>> 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.
Keeping a bookmark is really the easy part.
Getting search engines to make the user land right on the relevant
content is much harder.
What I like about the webhelp format (well, at least with my
modifications to it ...) is that the reading experience could be
altered by creating more "reading modes" in Javascript. Here's my
experiment:
http://docs.neo4j.org/lab/webhelp2/The TOC tree on the left is in a separate file and only loaded once,
then fetched from the browser cache.
The pages are simple HTML files, readable for any search engine.
The layout is created dynamically in Javascript, and doesn't have to
look that way at all.
WIth HTML5 we could load new pages dynamically, altering the address
bar to conform to what's being read at the moment. Lots of
possibilities in there. (load previous and next page so you can just
keep scrolling when reading)
Would be really interesting if Asciidoctor could produce a multipage
output where different themes could be used to provide features like
this on top.
/anders