Asciidoctor :: Discussion

CometD 3 Documentation ported to Asciidoc

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

2 messages Options

Simone Bordet

CometD 3 Documentation ported to Asciidoc

Hi all,

I wanted to share that the CometD project (http://cometd.org) moved from DocBook to Asciidoc for the CometD 3.0.0 documentation, that you can find online at http://docs.cometd.org/3/reference.

I used https://github.com/opendevise/docbookrx to convert from DocBook to Asciidoc. It's not perfect, especially on tables, but it did 90% of the job, and I had to review the whole documentation anyway.

The experience with Asciidoc has been really pleasant with respect to DocBook, so I definitely recommend the conversion if you plan to maintain the documentation for a while.

Integration with Maven was also smooth, and I am looking forward to the native PDF integration.

A couple of questions:

* Chunked output. IIRC I read that chunked output is considered an antipattern, but with mobile fruition of content is this still true ? I am currently undecided if chunked output is better or not (would require some sort of search bar, but that is easily achievable with a Google custom search), but perhaps SEO-wise a chunked output is better (though I am not a SEO expert) ? I know this is possible via Asciidoctor-Docbook-HTML, but I'd like to avoid to resurrect Docbook now that I got rid of it :)
* Edit-Fork-SubmitPull workflow. Speaking with Dan at conferences, what sold me into Asciidoctor was the (future?) ability for people to read the docs, find a typo, hit an "Edit" button for that paragraph, which would then perform a fork of the documentation on the reader's account on GitHub, edit there and on "Save" it would issue a pull request to the original project. I don't know if there is something like that already in place, but I'd be glad to know more and possibly contribute.

Thanks !

mojavelinux

Re: CometD 3 Documentation ported to Asciidoc

Administrator

Simone,

This is great news! I'm so happy to hear that your experience with AsciiDoc has been pleasant and that the converter got you most of the way there. We'll keep working to achieve an even better experience. As I like to say, "we optimize for author happiness" (to put a spin on the GitHub phrase).

Native PDF integration is coming along. I'll post to the discussion list soon on the status of that project.

On Mon, Jun 23, 2014 at 9:03 AM, Simone Bordet [via Asciidoctor :: Discussion] <[hidden email]> wrote:

A couple of questions:

* Chunked output. IIRC I read that chunked output is considered an antipattern, but with mobile fruition of content is this still true ? I am currently undecided if chunked output is better or not (would require some sort of search bar, but that is easily achievable with a Google custom search), but perhaps SEO-wise a chunked output is better (though I am not a SEO expert) ? I know this is possible via Asciidoctor-Docbook-HTML, but I'd like to avoid to resurrect Docbook now that I got rid of it :)

I'm not necessarily opposed to chunked output, just arbitrary and excessive splitting. (The default in the DocBook toolchain is dreadful. As an example of what I mean, see http://docs.fedoraproject.org/en-US/Fedora/20/html/Installation_Guide/s2-trouble-space-x86.html)

In general, I recommend chunking at the chapter level first, then breaking it up further if needed. The way chunking is handled in Asciidoctor EPUB3 is that each top-level include (i.e., the include for a chapter) delineates a separate HTML files in the generated output. The tricky part is maintaining references when the document is split up. We've done some work in that area, but there are still some changes that need to happen to make it better.

The takeaway is that adding a chunking option is on the roadmap after the release of Asciidoctor 1.5.0.

* Edit-Fork-SubmitPull workflow. Speaking with Dan at conferences, what sold me into Asciidoctor was the (future?) ability for people to read the docs, find a typo, hit an "Edit" button for that paragraph, which would then perform a fork of the documentation on the reader's account on GitHub, edit there and on "Save" it would issue a pull request to the original project. I don't know if there is something like that already in place, but I'd be glad to know more and possibly contribute.

It works just the way you describe it. I recommend creating a separate GitHub account so you can see how it works if you are a contributor (non-administrator) of the repository. Navigate to one of the files, click "Edit", GitHub forks the repo and gives you and editor...you make a change, preview that change, then send the pull request. I've made many changes using precisely this workflow.

Unfortunately, if you have commit access to the canonical repository, GitHub does not give you the fork workflow option and instead makes the change directly. I wish that could be disabled...or at least given a choice.

Cheers!

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen