Missing elements

[pbokoc]

The guide is IMO missing the following at the moment:

• Keyboard shortcuts - kbd:[key1(+key2+...)]. At the same time, this only works if you set :experimental: in the master file, I'm not really sure how we want to handle that. Keycombos are important and used quite a lot in some types of docs so I feel we should have them and tell people to use experimental, it doesn't seem to break anything.

• Admonitions - [NOTE], [IMPORTANT], [WARNING]. Those are used all the time and very useful. They don't need any special parameters, but the document should explain to people when to use each admonition, a la the old Document Conventions we used to put at the start of older guides. (Note = you might be interested in knowing this, Important = you might lose data if you don't know this, Warning = you will lose data if you don't know this).

• Tables - there's no mention of those. It's not a huge problem since it's basically just "do an asciidoc table", however other elements that are just basic adoc, like links or images, are explained in the doc so we should cover tables too. Preferably also show how to do multi-row/multi-column cells.

• The ADoc equivalent of xrefs, so we can point to internal IDs and get autogenerated links.

Notes on elements that are already included:

• "Code blocks" could use a link to a list of languages supported by the highlighter

• "Command blocks" a link to the ADoc reference explaining [subs=...] options, or better yet, just list useful options and what they do. We should also mention that yes, please add the prompt (# or $ based on whether the user is expected to be root or not), and don't add the current directory (foo]#). If there's consensus on that, of course - an argument could be made for including the current dir if we're telling the user to switch directories, since it helps people orient themselves.

[rkratky]

Keyboard shortcuts - kbd:[key1(+key2+...)].

Yep, true. This needs to be added. => #8

At the same time, this only works if you set :experimental: in the master file

Other recommended mark-up in these guidelines also requires that. For some reason, the doc doesn't mention this even though I'm pretty sure it used to. Needs fixing. => #9

Admonitions - [NOTE], [IMPORTANT], [WARNING]. Those are used all the time and very useful. They don't need any special parameters, but the document should explain to people when to use each admonition

This doc doesn't want to teach people how to write properly. This is purely about styling of various elements. As admonitions (AFAIK) cannot be marked-up/styled in any other way, there's no reason to talk about them (here).

Tables - there's no mention of those. It's not a huge problem since it's basically just "do an asciidoc table"

Exactly.

however other elements that are just basic adoc, like links or images, are explained in the doc so we should cover tables too

Links and images can be marked-up in a number of ways (various parameters can be specified), so we want to standardize on one way (what is the minimum that should be defined).

Come to think of it, this may be true for tables, too. Should be investigated. => #10

The ADoc equivalent of xrefs, so we can point to internal IDs and get autogenerated links.

I believe this is standard mark-up (<<id>> or xref:id), so no reason to include it.

"Code blocks" could use a link to a list of languages supported by the highlighter

Good point. => #11

"Command blocks" a link to the ADoc reference explaining [subs=...] options, or better yet, just list useful options and what they do.

Again, the aim is not to teach people to use adoc. That said, a link (above or below the table) to adoc reference and user manual wouldn't hurt. => #12

We should also mention that yes, please add the prompt (# or $ based on whether the user is expected to be root or not), and don't add the current directory (foo]#).

This request isn't about mark-up/style but about best practices for writing. So, these guidelines are not the right place for it. That said, this is one of the issues we have identified that should be standardized. The team has agreed to take it up next and possibly add such recommendations to the doc published by the Documentation Conventions initiative.

[lruzicka]

Hey,
I will add the line to the document and make a pull request.
Lukas

[pbokoc]

@rkratky I mostly agree, just one more thing about admonitions: even if we don't explain when to use each one, how about at least noting that the syntax is a bit different from other blocks (e.g. code) in that admonitions are delimited by ==== instead of .... or ----?

[lruzicka]

Will this markup build an admonition?
[NOTE]
....
Note?
....
Let me test it.

[lruzicka]

@pbokoc , @rkratky
So, the only possible mark-up for admonitions is:

[ADMONITION]
====
Something
====

Do we have to explicitly say that other delimiters will not work? We are saying to use the correct version already. I do not think we need any more explanation on that. Or?

[rkratky]

@pbokoc, I understand there's a potential for confusion, but there are many such areas. I wouldn't want this doc to slide towards "AsciiDoc help". If people use incorrect syntax (for anything, incl. admonitions), well, it happens. It's not the aim of this doc to teach people how to use adoc.

[swadeley]

@rkratky Re "not the aim of this doc to teach people how to use adoc."

Linking to the asciidoctor.org/docs/user-manual in Additional Resources is nice. Unfortunately, it does not mention the needs for + in +quotes. How about a "Known Issues" section at the bottom as a compromise?

[rkratky]

How about a "Known Issues" section at the bottom as a compromise?

+1

[lbopf]

Let me know if this is best raised in a new issue now, but I want to add some support to this point suggested by pbokoc:

• The ADoc equivalent of xrefs, so we can point to internal IDs and get autogenerated links.

While I agree that this is not the place to teach people to use AsciiDoc, I've searched through all of the 'Additional Resources' listed, and I don't see a place that clearly explains that leaving the square brackets empty after xrefs will automatically pull in the title that follows that ID, even if it changes, and why that can be useful. We've seen a few maintenance issues caused by folks thinking they needed to manually include a section title in their xref.

Internally, on the documentation teams I work with, we've provided the following example in a team document:

See xref:configuring_a_database[] (leave the square brackets blank to ensure that the title is pulled directly from the topic)

I think similar guidance would be useful and more visible in the Quick Reference.

If the consensus is not to be that prescriptive about xref usage, we could also include another example for comparison, like this:

See xref:configuring_a_database[this section]