Recommendations for multi-page and single-page documentation

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Recommendations for multi-page and single-page documentation

glaforge
Hi,

I'm playing with AsciiDoctor through the Gradle plugin, so I don't really yet have access to all the flags one can pass to the asciidoctor on the command-line... but hopefully, the plugin can soon expose some further configuration options -- thanks Andrés!

But I'm wondering what are the recommendations regarding outputting a big documentation in both multi-page format, and big single-page format, at the same time, hopefully without necessarily reparsing the docs twice.

Similarily, I might want to expose the documentation online on a website, but in a slightly different format standalone (in a ZIP for example). Again, does that mean parsing docs as many times as needed, to produce as many outputs with different combinations of stylesheets, javascript bits, etc?

Thanks for the advice

Guillaume
Reply | Threaded
Open this post in threaded view
|

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

LightGuardjp
Administrator

That's a good question. I think the answer as it currently stands with Asciidoctor is you'll have to run it multiple times. This something we should enable in core Asciidoctor, however, I feel it would be a larger change and we'll have to discuss how it would look on the cli. My initial thoughts are to add a separate attribute for multiple output runs as we can't pass multiple -b attributes currently. Unless we do further parsing of the attribute and make it delimited, that would be an easy change to get that part. The other, I describe below is much more work (I think). 


Actually now that I think about it, you would probably have to parse the docs multiple times anyway, unless we make some deep core changes to keep the ast around after we've done parsing. I'll let Dan comment once he wakes in a few hours, he may have a better idea. 

Sent from Mailbox for iPhone


On Fri, Apr 12, 2013 at 8:45 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

I'm playing with AsciiDoctor through the Gradle plugin, so I don't really yet have access to all the flags one can pass to the asciidoctor on the command-line... but hopefully, the plugin can soon expose some further configuration options -- thanks Andrés!

But I'm wondering what are the recommendations regarding outputting a big documentation in both multi-page format, and big single-page format, at the same time, hopefully without necessarily reparsing the docs twice.

Similarily, I might want to expose the documentation online on a website, but in a slightly different format standalone (in a ZIP for example). Again, does that mean parsing docs as many times as needed, to produce as many outputs with different combinations of stylesheets, javascript bits, etc?

Thanks for the advice

Guillaume


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

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

mojavelinux
Administrator
First, I would say don't worry about parsing the docs multiple times. Asciidoctor is fast as hell. The RichFaces documentation, which is just astronomically huge, parses and renders in 0.16 seconds. This is not a concern (and I'll be damned if I can't make it faster).

Now, as for the traditional outputs (single page, multi page, pdf)...the first solution I would propose is to chain it to the jdocbook plugin. Asciidoctor takes AsciiDoc and converts it to DocBook, jdocbook takes it from there and does what it's been doing for years. Add the pressgang tools into that and you get some pretty nice looking PDFs.

Here's an archetype that combines these two great plugins:


Kurt posted about this on the mailinglist yesterday. I spent yesterday experimenting with it and I ended up with the PDF of the AsciiDoc quick reference (after some color and style hacking of the XSL):


Having said that, part of the vision for Asciidoctor is to be able to work w/o the DocBook toolchain. Right now Asciidoctor can take a source file and create a single HTML page. Support for ePub and zipped result is prototyped, but not yet implemented.

...as for multi-page, or "chunked" output...I first have to say, I think it's a terrible reader experience. I *always* click on single HTML. Browsers are so unbelievably fast at rendering that this is not a problem for users to have a huge, huge, huge HTML document. Besides, if it's so huge, then it probably is too big and no one will read it (break it up into different manuals, not just splitting up all the chapters).

With that out of the way, the way in which you would create the single chapters is to either have Asciidoctor run on each chapter file, producing a standalone document, or you could work with the AST tree and split up the document and render the parts out manually. The problem, however, is that cross-references in the document aren't going to work as expected. That is one of the things that jdocbook solves.

How we move forward depends a lot on the requirements that are brought forth. We'll meld Asciidoctor to meet the needs of the users. I am totally open to that policy. I do urge you, though, to think about why you are creating output in a particular way (e.g., multi-page documents) and ask yourself if that is really what you want or you just did it because you always did it.

Btw, I'd love to see the jdocbook plugin w/ the pressgang tools additions work in Gradle. It's a nice stack.

-Dan


On Fri, Apr 12, 2013 at 8:56 AM, lightguard.jp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

That's a good question. I think the answer as it currently stands with Asciidoctor is you'll have to run it multiple times. This something we should enable in core Asciidoctor, however, I feel it would be a larger change and we'll have to discuss how it would look on the cli. My initial thoughts are to add a separate attribute for multiple output runs as we can't pass multiple -b attributes currently. Unless we do further parsing of the attribute and make it delimited, that would be an easy change to get that part. The other, I describe below is much more work (I think). 


Actually now that I think about it, you would probably have to parse the docs multiple times anyway, unless we make some deep core changes to keep the ast around after we've done parsing. I'll let Dan comment once he wakes in a few hours, he may have a better idea. 

Sent from Mailbox for iPhone


On Fri, Apr 12, 2013 at 8:45 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

I'm playing with AsciiDoctor through the Gradle plugin, so I don't really yet have access to all the flags one can pass to the asciidoctor on the command-line... but hopefully, the plugin can soon expose some further configuration options -- thanks Andrés!

But I'm wondering what are the recommendations regarding outputting a big documentation in both multi-page format, and big single-page format, at the same time, hopefully without necessarily reparsing the docs twice.

Similarily, I might want to expose the documentation online on a website, but in a slightly different format standalone (in a ZIP for example). Again, does that mean parsing docs as many times as needed, to produce as many outputs with different combinations of stylesheets, javascript bits, etc?

Thanks for the advice

Guillaume


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p119.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

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

glaforge
Regarding fast parsing time, that's good to know, and removes some worries I had.
When playing with asciidoctor through the Gradle plugin, for a very small document, it took like 6-7 seconds on my machine -- half of that being just the Gradle machinery. And as soon as I added a second small document, it went up to 9-10 seconds, which gave me the impression that parsing even small documents took quite long.
But that's perhaps a question of JRuby startup time? And perhaps also the Gradle plugin integration which somehow spins up a JRuby environment afresh each time too?

On the PDF aspect, I'm glad that you're progressing nicely here, and that it'll be possible to use Asciidoctor out of the box to do that PDF generation.

Now on the chuncked / single document, I have to somewhat disagree with you here.
The thing is that I want to rewrite the whole Groovy website and documentation.
I want a PDF output because folks like having a PDF handy to search into when offline, for example, and same thing for the full/single document.
But I also want chuncked documents because it's much easier for our users to just use Google and go directly right on the good page covering the topic they are searching -- instead of having to find the right spot in a huge document!
That said, I'll definitely have several manuals anyway, with, for example, the "language reference", the "metaprogramming guide", the "libraries guide" and what not.
But if we take the example of the "language reference", it's going to be a huge document if it were only one Asciidoc file. So I'd much rather split for easier collaboration on each sub-topics, and also to be able to publish that on the Groovy website as dedicated pages cover each and every aspect of the language.

So, I definitely think it's important to split the whole documentation in different manuals, of course, but each manual should be available both in chuncked and single document(s).

And ideally, of course, cross references should work out of the box when in chuncked and single modes!

Does my use case make sense?

(happy to further discuss it offline live if you're interested or need more context or background)
Reply | Threaded
Open this post in threaded view
|

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

mojavelinux
Administrator
In reply to this post by LightGuardjp
On Fri, Apr 12, 2013 at 3:14 PM, Dan Allen <[hidden email]> wrote:
First, I would say don't worry about parsing the docs multiple times. Asciidoctor is fast as hell. The RichFaces documentation, which is just astronomically huge, parses and renders in 0.16 seconds. This is not a concern (and I'll be damned if I can't make it faster).

Btw, this estimate is off by an order of magnitude. It's more like 1.6 seconds. However, it's highly dependent on the capabilities of the server and the configuration of Ruby/JRuby.

I've updated the Maven example that shows how to combine the Maven Asciidoctor plugin w/ the jdocbook plugin to get all the traditional DocBook outputs such as HTML, HTML Single and PDF.


This is also possible w/ Gradle since it has both an Asciidoctor plugin and a jdocbook plugin available. Anyone interested in hacking up a Gradle build that sits next to the pom.xml in this project?

We're still shooting for getting all this capability into Asciidoctor directly, but for the time being, you aren't left high and dry.

-Dan
 

Now, as for the traditional outputs (single page, multi page, pdf)...the first solution I would propose is to chain it to the jdocbook plugin. Asciidoctor takes AsciiDoc and converts it to DocBook, jdocbook takes it from there and does what it's been doing for years. Add the pressgang tools into that and you get some pretty nice looking PDFs.

Here's an archetype that combines these two great plugins:


Kurt posted about this on the mailinglist yesterday. I spent yesterday experimenting with it and I ended up with the PDF of the AsciiDoc quick reference (after some color and style hacking of the XSL):


Having said that, part of the vision for Asciidoctor is to be able to work w/o the DocBook toolchain. Right now Asciidoctor can take a source file and create a single HTML page. Support for ePub and zipped result is prototyped, but not yet implemented.

...as for multi-page, or "chunked" output...I first have to say, I think it's a terrible reader experience. I *always* click on single HTML. Browsers are so unbelievably fast at rendering that this is not a problem for users to have a huge, huge, huge HTML document. Besides, if it's so huge, then it probably is too big and no one will read it (break it up into different manuals, not just splitting up all the chapters).

With that out of the way, the way in which you would create the single chapters is to either have Asciidoctor run on each chapter file, producing a standalone document, or you could work with the AST tree and split up the document and render the parts out manually. The problem, however, is that cross-references in the document aren't going to work as expected. That is one of the things that jdocbook solves.

How we move forward depends a lot on the requirements that are brought forth. We'll meld Asciidoctor to meet the needs of the users. I am totally open to that policy. I do urge you, though, to think about why you are creating output in a particular way (e.g., multi-page documents) and ask yourself if that is really what you want or you just did it because you always did it.

Btw, I'd love to see the jdocbook plugin w/ the pressgang tools additions work in Gradle. It's a nice stack.

-Dan


On Fri, Apr 12, 2013 at 8:56 AM, lightguard.jp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

That's a good question. I think the answer as it currently stands with Asciidoctor is you'll have to run it multiple times. This something we should enable in core Asciidoctor, however, I feel it would be a larger change and we'll have to discuss how it would look on the cli. My initial thoughts are to add a separate attribute for multiple output runs as we can't pass multiple -b attributes currently. Unless we do further parsing of the attribute and make it delimited, that would be an easy change to get that part. The other, I describe below is much more work (I think). 


Actually now that I think about it, you would probably have to parse the docs multiple times anyway, unless we make some deep core changes to keep the ast around after we've done parsing. I'll let Dan comment once he wakes in a few hours, he may have a better idea. 

Sent from Mailbox for iPhone


On Fri, Apr 12, 2013 at 8:45 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

I'm playing with AsciiDoctor through the Gradle plugin, so I don't really yet have access to all the flags one can pass to the asciidoctor on the command-line... but hopefully, the plugin can soon expose some further configuration options -- thanks Andrés!

But I'm wondering what are the recommendations regarding outputting a big documentation in both multi-page format, and big single-page format, at the same time, hopefully without necessarily reparsing the docs twice.

Similarily, I might want to expose the documentation online on a website, but in a slightly different format standalone (in a ZIP for example). Again, does that mean parsing docs as many times as needed, to produce as many outputs with different combinations of stylesheets, javascript bits, etc?

Thanks for the advice

Guillaume


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p119.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597




--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

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

nawroth
In reply to this post by mojavelinux
Sounds nice with the parsing times.

Regarding multi-page output, I want to add that it provides a natural place to add comment threads.
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).

/anders
Reply | Threaded
Open this post in threaded view
|

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

mojavelinux
Administrator



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.

-Dan

--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

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

mojavelinux
Administrator
In reply to this post by nawroth
I'll also add them I'm so relieved that webhelp doesn't look like that horrible, horrible Eclipse Help system. It's so ugly it burns my eyes :)

-Dan


On Tue, Apr 16, 2013 at 3:40 AM, Dan Allen <[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.

-Dan

--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597




--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

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

mojavelinux
Administrator
In reply to this post by glaforge
I still owe you a response on this...I'll get to it shortly. I didn't want you to think I was ignoring it since I followed up later in the thread.

-Dan


On Mon, Apr 15, 2013 at 9:16 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Regarding fast parsing time, that's good to know, and removes some worries I had.
When playing with asciidoctor through the Gradle plugin, for a very small document, it took like 6-7 seconds on my machine -- half of that being just the Gradle machinery. And as soon as I added a second small document, it went up to 9-10 seconds, which gave me the impression that parsing even small documents took quite long.
But that's perhaps a question of JRuby startup time? And perhaps also the Gradle plugin integration which somehow spins up a JRuby environment afresh each time too?

On the PDF aspect, I'm glad that you're progressing nicely here, and that it'll be possible to use Asciidoctor out of the box to do that PDF generation.

Now on the chuncked / single document, I have to somewhat disagree with you here.
The thing is that I want to rewrite the whole Groovy website and documentation.
I want a PDF output because folks like having a PDF handy to search into when offline, for example, and same thing for the full/single document.
But I also want chuncked documents because it's much easier for our users to just use Google and go directly right on the good page covering the topic they are searching -- instead of having to find the right spot in a huge document!
That said, I'll definitely have several manuals anyway, with, for example, the "language reference", the "metaprogramming guide", the "libraries guide" and what not.
But if we take the example of the "language reference", it's going to be a huge document if it were only one Asciidoc file. So I'd much rather split for easier collaboration on each sub-topics, and also to be able to publish that on the Groovy website as dedicated pages cover each and every aspect of the language.

So, I definitely think it's important to split the whole documentation in different manuals, of course, but each manual should be available both in chuncked and single document(s).

And ideally, of course, cross references should work out of the box when in chuncked and single modes!

Does my use case make sense?

(happy to further discuss it offline live if you're interested or need more context or background)


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-tp118p129.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

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

LightGuardjp
Administrator
In reply to this post by mojavelinux


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. 
Reply | Threaded
Open this post in threaded view
|

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

rwinch
Reply | Threaded
Open this post in threaded view
|

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

nawroth
In reply to this post by LightGuardjp
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