Consolidate Asciidoclet documentation

[msgilligan]

There is a high-degree of duplication in the Asciidoclet documentation spread over three places:

• The Github project README.adoc
• The 1.5.0 Release Notes
• The Asciidoclet Guide on Asciidoctor.org

The source code for these docs should be consolidated for ease-of-maintenance and it should probably be published to a single place as well.

My recommendation is that the consolidated source be stored in src/docs/asciidoc/asciidoclet-guide.adoc within this project. That way it can more easily be kept in sync with the latest version of the code.

On the publication/distribution side, I'm looking for guidance from @mojavelinux and @johncarl81 as to what they think is best. I like the idea of having a nicely rendered and styled Asciidoclet Guide that can be linked to from the README, release notes, etc. I don't understand the publication/aggregation process for Asciidoctor.org and if it can pull content from this repository. Are there plans to use Antora going forward?

[msgilligan]

@mojavelinux @johncarl81 Any thoughts on how we should approach this? Where should the single/consolidated document source live? Where should it published?

[johncarl81]

The 1.5.0 Release Notes (and Write Javadocs in AsciiDoc with Asciidoclet) are blog entries and shouldn't be considered true documentation.

I like having the main project documentation, especially for a small project like this one, as the README for the project. This makes it easy to find because it's rendered as the home page of the project on github. The Asciidoclet Guide is simply a copy of the README and exists because Asciidoclet is part of the Asciidoctor OS community. If we need to bolster or consolidate the documentation I'd start with the README and add additional sources as links if necessary.

[mojavelinux]

The documentation for the Asciidoctor project is moving to Antora. I strongly encourage you to consider enlisting the documentation for Asciidoclet into that site. By doing so, all the concerns of building, publishing, and hosting the documentation for this subproject will be taken care of. All you have to worry about is the documentation itself. And you can leverage Antora's advanced cross references to make links to sections in the language and core processor documentation.

To get started, you'd just need to set up an Antora component structure under the docs folder. You can use Asciidoctor.js as a reference: https://github.com/asciidoctor/asciidoctor.js/tree/master/docs

In this new model, I strongly recommend keeping the README to just the essentials. With the documentation in a proper documentation site, it's a lot easier for readers to find the information they need.

We should also try to get away from this idea of a monolithic guide an instead create pages that focus on specific topics. That makes maintaining the docs easier and users are less overwhelmed. Like the Antora docs, we'll use something like Algolia search to help readers quickly find the information they need.

[mojavelinux]

And to be clear, I'll definitely be here to assist with the migration to Antora.

[johncarl81]

Sounds good @mojavelinux, do you have a version of the asciidoctor.js antora documentation hosted somewhere?

[mojavelinux]

You can find the repository where this is all happening here:

https://github.com/asciidoctor/docs.asciidoctor.org

You're welcome to join the party at any time. Once you have an Antora docs structure set up somewhere, perhaps in a branch, we can point Antora at it (antora-playbook.yml) and those docs will be included in the site.

[msgilligan]

Sorry I've been AWOL lately. (I've been very busy with work and family. I'm looking forward to having more time to help out, but it might be another month or so.) I'm looking forward to playing with Antora.

[mojavelinux]

Yeah! It's a good time to get back into it because things are really starting to get more organized.

The new docs site will be available later this month and should serve as an excellent reference. Antora is designed to be very simple (once the pipeline is set up), so it shouldn't require too much effort to chop up the docs into individual pages and get them published. And I'll be here to help out!

[apj68]

@msgilligan , I can take a stab at consolidating the docs. I'm not much an expert but I love the whole platform and I'm somewhat familiar with Antora (read: basic user). I've just ran around the horn trying to get asciidoclet working with asciidoctorj-diagram which leads to a fantastic goose chase over the web since virtually every sample out there are instructing for pre- or early-asciidoctorj and many without diagram so it can be confusing. When I finally got the configuration right it was giving jruby errors which resolved by using @devlauer's pull request (#104) and updated asciidoctorj libraries). To that I needed to add 'fr.jmini.asciidoctorj:file-logger:1.0.0' and 'com.google.guava:guava:20.0' to the classpath. It would probably help others in the future if you could merge that.

[mojavelinux]

I can take a stab at consolidating the docs.

🎉

If you need help with Antora, don't hesitate to @ me.

[apj68]

It looks like I'm too late to help with this one.. 😄 Asciidoclet looks to have already been migrated to the main Antora site by @abelsromero. Per Dan's comment here I could possibly prune down the github README.adoc and make reference to the main docs but @abelsromero seems to already have done a great job and in all honesty I think the gist of this issue is already complete.

[mojavelinux]

You're absolutely right. @abelsromero did a fantastic job of migrating the docs for inclusion in the new site. I do think the README could be further simplified so that there's no duplication, but you may want to consider making that a separate issue.

[abelsromero]

I could possibly prune down the github README.adoc and make reference to the main docs

Absolutely, go for it! I just stepped in for the bare minimum to keep the train going.