Posted by asotobu on
URL: https://discuss.asciidoctor.org/Custom-styles-support-tp441p452.html

Hello,

only one warning, be aware of using counters. Let me show an example where would be better to not use counters:

Let's say we are working a PRS (Product Requirement Spec) as:

storage-requirements.adoc

requirements

[[Req-1]]
----
*Req-1* Users shall be able to store data without any interruption
----

And then from a Design document you can do something like:

storage-design.adoc

Because of link:storage.requirements.html/#Req-1[Requirement-1] we shall use MongoDB ......



Note that in this case we are creating a cross-reference between different documents so you can trace why one decision was taken.

With a counter you will never know the requirement number at write time so you won't be able to refer that requirement from another document. In my opinion counters should be used in documents that won't be referenced by any other document, for example in SDS documents.