Asciidoctor advanced feature possibilities

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

Asciidoctor advanced feature possibilities

CuttingWide
Hello together,

first let me say, I'm greatly appreciating the effort that went into all of Asciidoctor!

I'm doing a review of the documentation strategy at my employer. Currently we're still using Word and that's obviously not the best choice.

About the environment
- Building machinery for the tire industry
- The documents we need to write are "classical" operating instructions.
- A typical manual usually has around 300-400 pages overall, coming from 4-5 separate documents in Word currently.
- We have to follow for regional regulations or normative requirements (mostly safety-related). So for example, we need to use different warning signs when shipping to the US.
- The documentation contains a lot of images and drawings, is also relatively colorful (as again, normative requirements).
- Software documentation is usually not a part of our instructions (aside from explaining user interfaces).
- There are currently 5 workers assgined to writing these documents (2 full-time, others part-time).
- The compared solutions are (likely) going to be: Word (current status), Asciidoc(tor), ReSt+Sphinx, DocBook, FrameMaker, Latex
- Although other formats are of course gaining importance, the main way of publishing will still be PDF for some years (especially because of Asia).


Now, I already did quite some feature research, tests and browsing Google for informations on Asciidoctor. The documentation is already quite good and I found a lot of answers. However, I wasn't able to find out how to do the following topics.

As I'm doing the benchmarks, I basically need the following info for each:
- Is it possible "built-in", so without the need to do something customized? Would be considered to be the case if I can write it as basic markup in the files (so practically anything that doesn't need custom code or YAML).
- If not built-in, would it generally be possible to create an extension for it?
- If so, about what effort are we talking (ofc only very vague, low/high/extraordinary)?

Note: Please take into mind, that I don't want to discuss if all points are meaningful approaches. I know, they're used currently and I know also that these questions will come up. For the moment I'm merely interested in the possibilities.

So, I'm looking for info about the following features:
- Multiple TOCs - for example one "big" at the beginning of the manual, that lists all "Chapters". More specific ones at the start of each chapter.
- Table of figures - we need to provide a list of all used images/drawings in the document.
- Table of custom defined caption - For some customers, we explicitly need to provide a list of all drawings (without images). In word this is currently done with a custom caption and filtering for that when creating the list. A more software-like example might be a list of all "Code examples" in a document.
- Custom icons for admonitons - As said, we need to use different warning signs depending on the country where the machine will be delivered to.
- Multiple indexes in the same document - Think for example of one "regular index" - word-based approach and one topic-based approach (for Example "Best Practices").
- Custom commands - Commonly used in Latex ofc. Think of new macros to have more or different admonitons for example.
- Conditional content - Lets say the same machine is delivered twice. But once the destination is Asia (usually EU regulations) and the second time US (NFPA/OSHA regulations). Can I build the documentation in a way that the same content is used except marked passages that're switched as needed? For example I want to refer either to the term "ISO 13849" in the EU, but for US I want to insert "NFPA 79" at the same place.

Looking forward to some thoughts and thanks again!

Greetings
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor advanced feature possibilities

htmfilho
Hello,

I'm very curious to see the development of this discussion. I love to see real world cases of documentation production :-) That's very interesting.

Despite not being (yet) a expect on the subject, I have a few suggestions to give. They're in line...

On Wed, Feb 14, 2018 at 10:17 AM, CuttingWide [via Asciidoctor :: Discussion] <[hidden email]> wrote:

- Software documentation is usually not a part of our instructions (aside from explaining user interfaces).

I wrote a post last month about software documentation as a user manual in order to concentrate the entire application description in a single document: http://www.hildeberto.com/2018/01/rethinking-software-documentation.html. I think what you're doing (instructions explaining user interfaces) is more valuable.
 
- There are currently 5 workers assgined to writing these documents (2 full-time, others part-time).

Working with a raw text based source plus a version control system like Git is definitively a plus to enable parallel work in the same documentation.
 
- The compared solutions are (likely) going to be: Word (current status), Asciidoc(tor), ReSt+Sphinx, DocBook, FrameMaker, Latex

I think you shouldn't even consider Word anymore after my previous point. The time you will save is worth replacing Word.
 
- Although other formats are of course gaining importance, the main way of publishing will still be PDF for some years (especially because of Asia).

PDF is indeed our favority output format (https://uclouvain.github.io/osis-internship/), but we also generate HTML to enable contextual help in the application. Depending on the page the user is in, the help link points to a particular part of the HTML documentation.
 
As I'm doing the benchmarks, I basically need the following info for each:
- Is it possible "built-in", so without the need to do something customized? Would be considered to be the case if I can write it as basic markup in the files (so practically anything that doesn't need custom code or YAML).
- If not built-in, would it generally be possible to create an extension for it?

The problem with extensions is the content becomes dependent on the extension. You would need to version the extension together with the content so other people and automation scripts would use the proper version when generating the documentation. It is just one more thing to manage, but that is not a big deal giving your already complex scenario.

Here is the documentation of extensions in Asciidoctor: http://asciidoctor.org/docs/user-manual/#extensions

 
So, I'm looking for info about the following features:
- Multiple TOCs - for example one "big" at the beginning of the manual, that lists all "Chapters". More specific ones at the start of each chapter.
- Table of figures - we need to provide a list of all used images/drawings in the document.
- Table of custom defined caption - For some customers, we explicitly need to provide a list of all drawings (without images). In word this is currently done with a custom caption and filtering for that when creating the list. A more software-like example might be a list of all "Code examples" in a document.

I think you need extensions for these three points.
 
- Custom icons for admonitons - As said, we need to use different warning signs depending on the country where the machine will be delivered to.
- Conditional content - Lets say the same machine is delivered twice. But once the destination is Asia (usually EU regulations) and the second time US (NFPA/OSHA regulations). Can I build the documentation in a way that the same content is used except marked passages that're switched as needed? For example I want to refer either to the term "ISO 13849" in the EU, but for US I want to insert "NFPA 79" at the same place.

Every time I have customization conditions I use includes. I decompose the documentation in several small files and I compose them according to each need. So, I think you can do the same here + write some scripts to automate the workload.
 
- Multiple indexes in the same document - Think for example of one "regular index" - word-based approach and one topic-based approach (for Example "Best Practices").
- Custom commands - Commonly used in Latex ofc. Think of new macros to have more or different admonitons for example.

I didn't get these two points. I hope you find something useful.

Regards,

Hildeberto Mendonça
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor advanced feature possibilities

abelsromero
In reply to this post by CuttingWide
As a quick comentary, all of the requirements are doable, but some require extensions. This has 3 drawbacks:
* You need to code them and define the build process: in that regard there are many options in both Ruby and Java. Imho, not a major issue for the cases you need.
* User experience. Word offers a WYSIWIG experience that Asciidocotor previewers don't offer. This is something to manage with users. Again, for me not a major user, but may requires some expectation and change management effort if you find reluctant users.
* Some extensions are not backend independent. That means, that you will need to learn a bit about prawn (Ruby library used to generate the PDF) and those extensions will only work to generate PDF.

Probably you should have a look at the extensions examples to get an idea of what can be done:
https://github.com/asciidoctor/asciidoctor-extensions-lab

CuttingWide wrote
So, I'm looking for info about the following features:
- Multiple TOCs - for example one "big" at the beginning of the manual, that lists all "Chapters". More specific ones at the start of each chapter.
- Table of figures - we need to provide a list of all used images/drawings in the document.
- Table of custom defined caption - For some customers, we explicitly need to provide a list of all drawings (without images). In word this is currently done with a custom caption and filtering for that when creating the list. A more software-like example might be a list of all "Code examples" in a document.
As you can see in this comment, it is possible: https://github.com/asciidoctor/asciidoctor-pdf/issues/456#issuecomment-359861493

-Effort low: I imagine you can have a look at the source code to see how the toc is build and create a TreeProcessor that works for PDF and other backends workin only with AsciidoctorAPI.

CuttingWide wrote
- Custom icons for admonitons - As said, we need to use different warning signs depending on the country where the machine will be delivered to.
- Cusotmizable
- Effort low.

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/custom-admonition-block.rb

This is for HTML, but offers some idea.

CuttingWide wrote
- Conditional content - Lets say the same machine is delivered twice. But once the destination is Asia (usually EU regulations) and the second time US (NFPA/OSHA regulations). Can I build the documentation in a way that the same content is used except marked passages that're switched as needed? For example I want to refer either to the term "ISO 13849" in the EU, but for US I want to insert "NFPA 79" at the same place.
- "Built-in"
You can define `if` blocks with http://asciidoctor.org/docs/user-manual/#conditional-preprocessor-directives.
Just pass an attribute with the target destination.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor advanced feature possibilities

rockyallen
In reply to this post by CuttingWide
We have very similar requirements, and decided to use asciidoctor->docbook->fop to get the formating right, as the options in asciidoctor-pdf are quite limited at the moment.
Specifically:

- Multiple TOCs - for example one "big" at the beginning of the manual, that lists all "Chapters". More specific ones at the start of each chapter. - BUILT IN to docbook

- Table of figures - we need to provide a list of all used images/drawings in the document.  - BUILT IN to docbook

- Table of custom defined caption - For some customers, we explicitly need to provide a list of all drawings (without images). In word this is currently done with a custom caption and filtering for that when creating the list. A more software-like example might be a list of all "Code examples" in a document.  BUILT IN to docbook (you have tables, figures, equations, examples, and you could re-purpose one of these for specials)

- Custom icons for admonitions - As said, we need to use different warning signs depending on the country where the machine will be delivered to.  BUILT IN to Asciidoctor

- Multiple indexes in the same document - Think for example of one "regular index" - word-based approach and one topic-based approach (for Example "Best Practices"). - pass, but I suspect you could do it with a docbook customisation layer (XSL).

- Custom commands - Commonly used in Latex ofc. Think of new macros to have more or different admonitons for example. - You already have 5 admonition types, with customisable icons and formatting.  can you re-purpose some of them?

- Conditional content - Lets say the same machine is delivered twice. But once the destination is Asia (usually EU regulations) and the second time US (NFPA/OSHA regulations). Can I build the documentation in a way that the same content is used except marked passages that're switched as needed? For example I want to refer either to the term "ISO 13849" in the EU, but for US I want to insert "NFPA 79" at the same place.  - BUILT IN to Asciidoctor.

For very simple changes like this, use attributes such as

:standard: NFPA 79

or

:standard: ISO 13849

then put {standard} in your document.

For multi-line changes, create an attribute

:country: UK or
:country: US

and  wrap the variant text in ifeval::[country=US] in the asciidoc source.

But you might want to think a bit wider. Putting lots of ifdef and ifeval in a document rapidly leads to spaghetti. Break you content up into small "fragment" files, then create an "assembly" file  for each new document that is just  a set of attributes and includes of the fragments (no other content). This gives maximum flexibility and re-use, and works much better with source code control tools.


Just my experience.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor advanced feature possibilities

wolandscat
In reply to this post by CuttingWide
This a blog post from a couple of years ago, about moving away from FrameMaker (after 20 years!) to Asciidoctor.

The kind of docs we do you can see here - just click through any of the links near the top of the page - they are technical specifications for health information systems, that mix diagrams (done in draw.io), UML diags and extracted class tables (we wrote an extractor, it is open source), syntax specs (Antlr) and programming source code files.

Since I wrote that post, I've learned a lot about Asciidoctor. It's very powerful, and everyone likes our new specification documents. Things that might annoy you:

* complex tables. They are really painful. See this specification; now see the source files.

* PDF is still not ready for prime time, but the post above about DocBook probably addresses that.

* bibliographic references work, but are not ideal, if you want shared bibliography files (e.g. bibtex files) with only used references included in each document.

* some markup is non-trivial, and you probably won't remember it, but the documentation is very good and pretty up to date.

There are tools I'd really like to see for building tables and also bibliography / references, and a smarter source editor would be good (I use brackets for now). However, the current manual methods are tolerable. Overall, the tool is excellent, and the quality is very good - things work as documented with only the rare exception.

Also, the community and developer response is generally excellent. I never thought I'd be using this kind of tool after 20 years of FrameMaker, which is the killer tool for xrefs, WYSWYG, indexes, and many other long-document needs, but for a whole lot of other things, it is way behind (see the post). And Adobe support and licensing is just abysmal.

In the interests of objectivity, other tools you might want to look at is Madcap Flare (which I looked at briefly, and looked ok) and a new thing called Paligo, about which I know nothing. These are closed source commercial tools.