Ben Hardesty started working on the document.

Robert Krátký offered his services to Ben to help with this.

The information about IDs in the templates can be confusing, at least for AsciiDoc novices.

Here are a few suggestions for improvements:

• The [id='my-concept-module-a'] does not match the [id='concept-explanation-{context}']. I think it would be more effective for both examples to match...right now the syntax is too different.
• The education provides a best practice/recommendation of a prefix for file names (con_, etc), and the template says the ID should match. Therefore, the best practice should be reflected in the template. The prefix should be used for the filename and ID. (Even if you note that it is best practice, follow what your library does, etc.)
• I think it would be better to get rid of the "my-xyz..." as an example and using some more real examples, such as "what-is-foo" or "starting-the-foo" or "foo-parameters." Using a name that is more real for each module type is a simple reminder of what that module's focus should be and how the module title should be worded.
• For someone who has not been working in AsciiDoc yet, I wasn't sure how to interpret the {context} right away--so it took a few moments to process. That's another place where a "real" ID example could help the writers less familiar with AsciiDoc realize that the {context} is code that stays (not some kind of variable to replace): [id='con_what-is-foo-{context}']. For newbies, it would also probably be better to explain it a bit more: "The context attribute (coded as "-{context}" at the end of the ID string) is included in every ID...." or something similar.

Current template: https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/files/TEMPLATE_ASSEMBLY.adoc

This expects that assemblies are basically just a metaprocedure, not a collection of various modules based on user stories. There are also other inaccuracies that we should look at.

The repo's readme file points to a non-public mailing list:

Any Questions?
Send an email to our mailing list ([email protected]).

The reference should be removed, or the list opened.

I suspect a few people (myself included) don't look at the modular docs document as much as we should because it's become a fairly bulky document. I'd recommend either reviewing it and getting rid of the bulkier parts that are not strictly necessary, or just creating a checklist document that contains the basics someone needs to get up and running:

• Module types & templates
• Assemblies: what they are, an example.
• Things you should not do (for example cross-linking between modules or other things that you absolutely should not do because .
• Things you should do (titles=IDs, hyphens or underscores, etc.)

A checklist would be an easy way to get new hires onto the basics, and serve as a quick reference to settle discussions on what practice is the recommended way to do something. We can also point people to the detailed doc for further details, if necessary.

Here's an example of the checklist we used for the peer review: http://ccs-jenkins.gsslab.brq.redhat.com:8080/job/peer-review-branch-master/lastSuccessfulBuild/artifact/index.html#peer-review-checklist

This issue requires that modular docs mandate that we use the same structure for all new repositories, and have all older repositories plan on migrating to the new structure.

Although the guidelines recommend how we create modules and assemblies including how to name them, it makes no requirements on the way these are structured into a repository. It also doesn't provide any guidelines on how folders should be named, where you should keep the modules and assemblies, how to handle nested modules (if any), location of variables, symbolic links and images.

All this is required to make sure that the tooling team has a consistent repository structure to deal with instead of creating workarounds for every edge case.

This should be mandatory for every new repository.

On ubuntu 17.04

nicolas@ni27:~/test$ sudo apt install asciidoctor
...
Setting up asciidoctor (1.5.4-2) ...
...
nicolas@ni27:~/test$ git clone https://github.com/redhat-documentation/modular-docs.git
nicolas@ni27:~/test$ cd modular-docs/
nicolas@ni27:~/test/modular-docs$ scripts/buildGuides.sh
=== Building all the guides ===
/home/nicolas/test/modular-docs
Building /home/nicolas/test/modular-docs/files
scripts/buildGuides.sh: line 88: ./buildGuide.sh: No such file or directory
Building /home/nicolas/test/modular-docs/modular-docs-manual

********************************************
 Building modular-docs-manual
********************************************

Building an asciidoctor version of the modular-docs-manual
Input file: master.adoc
  Time to read and parse source: 0.03246
  Time to convert document: 0.01570
  Total time (read, parse and convert): 0.04816
Building the ccutil version of the modular-docs-manual
./buildGuide.sh: line 52: ccutil: command not found
modular-docs-manual (AsciiDoctor) is located at: file:///home/nicolas/test/modular-docs/modular-docs-manual/html/modular-docs-manual.html
Build of modular-docs-manual failed!
See the log above for details.

Build Results:
ERROR: Build of modular-docs-manual failed. See the log above for details.
Please fix all issues before requesting a merge!

I cannot find anything relevant regarding ccutil. The html seems to build fine, to what is the message relevant?

I had a hard time finding the templates; would be great if the directory that contains the templates was actually named '/templates." Thanks!

I know #66 was just merged, but I think I've heard enough negative feedback (and I'm not a fan of the change myself) that I feel compelled to open this issue.

Separating the anchor ID by a single hyphen makes debugging and potential automated changes in the future more difficult by losing the bit of information where the anchor id ends and the context begins. This was brought up in #66 several times, but was ignored and the PR was merged nonetheless.

Consider:

[id="booting-rhel-installation-dvd"]

versus

[id="booting-rhel_installation-dvd"]

In the second example, I can easily see that booting rhel is the name of the module, whereas in the first example, it could be booting-rhel-installation. This is an inconvenience when debugging build errors, but it's downright catastrophic when you need to do any automated transformations using a script.

The original proposal to use double quotes was shunned because they kept being replaced with an m-dash, which was solved by mandating double quotes instead of single quotes in anchor IDs (see #91), so it should not be a problem any more. I therefore propose to explicitly allow anchor-id_{context}, but recommend anchor-id--{context}, and for the sake of future changes, recommend refraining from anchor-id-{context}.

WDYT?

As the ci.centos.org solution seems to have many external dependencies, use Travis CI as an interim(?) solution.

The modular docs effort in CCS has produced a great guide available here. However, referring to PR#65, there has been a request for a condensed guide for those who are familiar with the concepts behind modular documentation BUT still want a way to reference the info quickly.

I have proposed: https://docs.google.com/document/d/188ysdKU4u5OwdrSj625saltfCnjpyW9yxxoyRUjkQIY/edit

While the template examples and rendered examples are nice to see, it would also be nice to be able to see the ascii-doc source of the rendered examples. (Since the guide is publicly available, the examples would need to be upstream code examples most likely. )
As a writer, I would find this very useful and helpful.

What does a standalone and reusable module need to look like?

Module granularity. What level of information constitutes a module?

With additional resources (in modules and assemblies), we definitely want to avoid writers adding resources just for the sake of having them. Additional Resources should always link to relevant resources only.

Right now, this is what we have in the manual:

Writing Additional Resources

The additional resources list links to other material closely related to the contents of the concept module: other documentation resources (such as assemblies or modules), instructional videos, labs, and similar resources.

Focus on relevant resources that are likely to be of immediate interest to the user. Do not list every resource that could conceivably be related.

The modular doc templates (assembly, procedure, concept, reference) all use arbitrary titles for the titles of the intra-module or intra-assembly components . For example:

.Prerequisites
.Procedure
.Related Information

These arbitrary titles are not always displayed properly when published, so we might want to consider changing them to discrete headings. For example:

[discrete]
== Prerequisites

[discrete]
== Procedure

[discrete]
== Related Information

This would involve updating each of the templates, and updating the assembly and module guidelines (which use the templates) to use discrete headings.

The anchor IDs in the template files are not consistent.
The Assembly anchor and Concept anchor IDs have -{context}.
The Procedure and Reference anchor IDs have _{context}.

Examples from template files:

[id='a-collection-of-modules-{context}']
[id='concept-explanation-{context}']
[id='doing-one-procedure_{context}']
[id='reference-material_{context}']

This issue includes several questions, I believe that for most of them we already came up with an answer, though. This issue should record the discussion and decisions in an open manner and track what changes should we done in the guide.

1. What subheading to use for the prerequisites section. I believe that we decided to use "Prerequisites". Any objections?

2. What subheading to use for the procedure itself. I think (from what I seen, that is is "Procedure") + is it a good idea to repeat the name of the procedure module in that title (for example Procedure: Changing the User Name)? Cons: duplication, Pros: possible better results when in searching results? Can someone who is in contact with JP Shermman check? (Nacia, Betty?)

3. What subheading to use for the additional details sections? I believe we decided to use "Additional Resources". Any objections?

4. Should we use the [discrete] tag for the subheadings so they don't show up in TOC? I believe that this is what we are already doing, but just want to confirm.

In addition, the guide should state why whatever we decide is recommended to follow (be consistent, cross-product reuse of modules, etc).

In the reference template, we still have :

[#reference-material_{context}]

instead of

[id='reference-material_{context}']

The optional sections of the procedure template: "Results" and "Next Steps" could be added to Procedure Template and Modular Docs Guide.
I propose that we add both sections "commented out" with a brief description of the use case.
This provides an obvious location and a reminder to add verification step(s) where possible (Results) and to indicate what procedure (if any) the user should consider next.

Since this is a public repository we might want to remove links to internal resources such as Mojo.

Hi,

We are currently discussion following issue. We have two assemblies which are included into multiple sections and link to each other:

- assembly-X (context=ctx-x)
    - assembly 1  <--\
    - assembly 2  ---/
- assembly-y (context=ctx-y)
    - assembly 1  <--\
    - assembly 2  ---/

Since each of these sections have different context,m we currently set the link like this using the {context}: xref:assembly-1-{context}. And it works fine.

However, if we include the module also somewhere else, like for example this, it will stop working.

- assembly-X (context=ctx-x)
    - assembly 1  <--\
    - assembly 2  ---/
- assembly-y (context=ctx-y)
    - assembly 1  <--\
    - assembly 2  ---/
- assembly 2 --------------> ?

On the other hand, if we use hard coded context instead of {context}, such as this: xref:assembly-1-ctx-1, it also doesn't work perfectly. Because it always links into one particular section and leads the user out of context.

- assembly-X (context=ctx-x)
    - assembly 1  <--\       <-----------\   <--\ 
    - assembly 2  ---/                   |      |
- assembly-y (context=ctx-y)             |      |
    - assembly 1                         |      |
    - assembly 2 ------------------------/      |
- assembly 2 -----------------------------------/

Is there any recommended approach how to deal with this?

Thanks

Is a release notes template/guidelines within the scope of this project?

If we are publishing release notes through the same system, would we build them using the existing templates, or should we have a template for this?

Note: I think that we don't need a separate template, but I thought I should raise the question anyway. We should be trying to be more consistent in the format we use to provide a more consistent customer experience.

Templates currently use block ".Titles" for module components like "Prerequisites", "Procedure", or "Additional resources". For example:

.Prerequisites

I propose to change this recommendation to this title markup:

[discrete]
== Prerequisites

The AsciiDoc documentation[1] actually states that block titles are designed to work as titles for the subsequent paragraphs, lists, or tables, not as mid-section titles like those in the templates. Also, Red Hat's publication tool chain doesn't always handle ".Titles" consistently.

[1] http://www.methods.co.nz/asciidoc/userguide.html#X42

This also relates to doc-guidelines, asciidoc-markup-conventions and community-collaboration-guide.

You have some good content here and I wanted to adopt some parts for https://pagure.io/fedora-docs/documentation-guide and somehow expected that this would maybe be CC-BY-SA. But since it doesn't state that anywhere I have to assume that it can't be adopted for reuse in other docs. I hope you can reconsider this.

Hi everyone,

I'm currently in the process of putting together a user story that is predominantly made up of modules from a number of user stories. The biggest issue I'm having by far is reusing modules that link to other modules.

When a cross-reference (xref) exists that points to another module, I have two options:

1. I can use conditionals to remove that link from my particular user story.
2. I can pull in the module that it links to.

The second option tends to create a cascade effect of pulling in more and more content that might only be vaguely related to the user story I'm trying to create.

The first option can result in spaghetti code and possibly break other stories, particularly where assemblies are included within other assemblies. It also doesn't really scale when we think about reuse across products and all possible user stories.

The current modular docs templates, as well as the Modular Documentation Reference Guide, advise including links to additional resources closely related to the contents of the module ("other documentation resources (such as assemblies or modules)..") within the module.

I am proposing that instead of providing cross-references to other modules within modules, they should only be added to the assembly file(main.adoc). Doing this results in the link only appearing in the assembly where the linked module already exists and allows more flexible module reuse across multiple assemblies without needing to add conditionals everywhere.

For example:

include::product-migration-guide/migration-configure-kie-server-proc.adoc[leveloffset=+1]
For information about installing {PRODUCT} on {EAP_LONG}, see xref:eap-dm-install-pro[].

renders the following sentence as though it were a part of the preceding module:
"For information about installing Red Hat Process Automation Manager on Red Hat JBoss Enterprise Application Platform, see Installing Business Central from the ZIP file "

TL;DR - We should only be cross-referencing between modules in the actual assembly files, rather than in modules themselves to make module reuse more flexible.

The OpenShift team is dealing with this issue for some content that they are currently working on. Here is a Google Docs version of the content, which is passworded:
https://docs.google.com/document/d/1qgf6hd205X6jNSc7vCHlVr1IuKIVJBWTKz9UQBTKITI/edit#

Any thoughts or recommendations are welcome? @kalexand-rh , do you have anything to add?

The templates currently say this:

// Do not change the ID to make sure existing links keep working

This confused some people because this sentence can be interpreted as a requirement to keep the template ID: [#doing_one_task]

https://redhat-documentation.github.io/modular-docs/#forming-assemblies

See 3.2.3. Additional Resources. The link to the adoc file doesn't work - 404: Not Found.

Proposed structure of the section about procedure modules: Creating Procedure Modules (assembly):

1. Definition: a ‘do’ module (concept module)

• As short as possible
• Must include that a procedure module is not just steps
  EDIT: ALL DONE: Done for procedure modules, concept modules, reference modules, and assemblies.

2. Guidelines (concept module)

• Review the current guidelines as a group
  EDIT: ALL DONE: Done for procedure modules, concept modules, reference modules, and assemblies.

3. Additional Resources

• Link to templates
  EDIT: ALL DONE: Done for procedure modules, concept modules, reference modules, and assemblies.
• Link to examples (Each team member nominates 1 or 2 (?), we pick the best examples.)
  EDIT: Done.

This issue does not track changes to the templates. See #12 and #11.

It looks like we may be greatly over-complicating the process for reusing modules within an assembly.

Consider that Asciidoctor automatically generates a unique ID for every section in a document. It ensures that each ID is unique even for included .adoc files. In other words, if you include the same module twice in an assembly, Asciidoctor will generate two separate, unique IDs for those modules.

I verified this by creating a test assembly and then including the same module three times:

= Test Assembly
This assembly is a test. This is only a test.

include::module1.adoc[leveloffset=+1]
include::module1.adoc[leveloffset=+1]
include::module1.adoc[leveloffset=+1]

The output was built without error, and Asciidoctor generated a unique ID for each module1.adoc inclusion (module, module-2, and module-3).

Therefore, is there a reason why we have defined the mod docs standards to require, 1.) manually overriding the auto-generated ID for every module title, and 2.) using attributes to guarantee uniqueness in each ID? If not, it would be much simpler and quicker to just let Asciidoctor generate unique anchor IDs for modules.

Even if this won't work for some reason, we could still use the built-in :idprefix: attribute to manually override an automatically-generated ID. For example, if you defined this (probably just once in the main attributes.adoc file):

:idprefix: {context}

Then in an assembly, you could apply the unique context to an included module:

:context: assembly-1-name
include::con_module-A-being-reused.adoc

In this case, if the title of con_module-A-being-reused.adoc is "Module A", then the automatically-generated anchor ID for the module would resolve to assembly-1-name-module-a.

As discussed in ccs-mod-docs distro list with email subject "Clarification on block heading vs. sub-heading for prereqs, procedures, etc.", I've submitted PR #56 to revert sub-headings for procedure, prereqs, etc., to block headings. Rationale provided in the PR.

The question that came up when we were reviewing sample modular docs (flagship or topnotch modular docs) is:

• How should we format the Prerequisites section if there is a single prerequisite? Should the title still be "Prerequisites"? Should the list be bulleted even if it's just a single prerequisite?

At this point, there's no explicit guidance. But the current recommendations from @ChristyWatkins, Betty Prioux, and me are:

• Yes, let's bullet the list even if it's just a single bullet (based on bulleted list recommendations from the IBM Style Guide).
• Let's always make the title "Prerequisites" even if there is just a single prerequisite.

Betty, Christy, and I all prefer to keep the formatting consistent for ease of scanning. We would like this to be an official recommendation in the Mod Docs Reference Guide.

@sterobin writes in #19:

What value is achieved by naming files by module, such as proc-creating_guided_decision_tables? That is, why is it helpful to have files listed by module type?

At the risk of misinterpreting what you said in, let me present the following argument (in case I indeed misinterpreted what you said, feel free to correct me):

• You write that you do share our view that anchor IDs should not diverge from file names very much.
• You also write that you agree with our view that anchor IDs should not diverge from the module heading very much because of the URLs.

The above necessarily means that, by transition, you agree that file names should not diverge very much from the module title. From this, I infer the following:

If file names should not diverge much from module headings—which provide no meaningful sorting capability—and we need to add a piece of text to it (the module type), we can either:

• make it a suffix, not gaining any sorting capability, or
• make it a prefix, gaining a not particularly helpful, but still non-trivial sorting capability.

As a side note, I consider prepending subject matter (again, a free-form string) a considerable deviation from the module heading.

cc @rkratky @asteflova

For example, each team member can nominate 1 or 2 (?), we pick the best examples.

EDIT: But we actually have examples of modular books now -- the books linked to from the appendix with module/assembly examples. A better idea seems to describe the structure of a modular repo and maybe include a simple template.

Modules are the fundamental building block of modular docs. However, they're not necessarily atomic in that there are occasionally opportunities to reuse "chunks" of text across modules. It would be helpful to develop some guidelines on how to handle this use case to avoid spaghetti-fying our docs (i.e. transcluding a portion of a module directly into another module).

Some initial thoughts:

• Reusing chunks of text across modules should be done with caution. Reuse inherently increases maintenance complexity, and in some cases, the "inefficiency" of having a paragraph duplicated in two different modules might be better than dealing with the extra complexity of reusing the paragraph.

• As much as possible, there should be a standard place/location where all "fragments/snippets" of reusable text are stored. This prevents the spaghettification effect where a module reuses multiple snippets, each of which are included from different modules (in other words, it's really tough to maintain reusable chunks of text when those chunks are randomly sourced from all over the doc repo). Two possible options:

  • Use a single "fragments" .adoc file to hold all reusable chunks of text. Each "chunk" could be delimited by AsciiDoctor tags (http://asciidoctor.org/docs/user-manual/#include-partial). To include a chunk in a module, you would use the tag attribute to specify the chunk you want to include (as opposed to the entire file). The benefit of this option is fragment maintainability: all reusable chunks are stored in a single file, so authors never have to go "hunting" to track down where a reusable chunk is located. The downside is that the tagging required can easily get complex and difficult to maintain.
  • Put each chunk of reusable text in a separate .adoc file. Define a standard file-naming convention to clearly identify them (i.e. use a "fragment-" prefix). Since each chunk is a separate file, they can be included in modules using normal include statements. This option would be easier to use than the tagging option, and it avoids the issue of transcluding portions of one module directly into other modules. Scalability might be a concern though, since you could end up with lots of "fragment-" files.

Hey all,

We should provide a section in the reference guide to indicate what parts of the reference guide are mandatory and what is left for the individual teams to decide.

One of the goals (I hope) of this and the related initiative of FCC is to standardize the processes and the way we write our docs going forward. This reference guide is a great initiative towards that goal but it leaves it up to each team to decide which parts they want to implement, if any.

I worry that this will lead to a situation where everyone is doing their own thing; taking in parts that the teams are comfortable adapting and leaving others. While some of this is unavoidable considering we are working with multiple upstream communities, we should be able to mandate many or most of the guidelines.

We should mandate (in the context of modular docs):

• file name structures
• module location structure
• assembly location structure
• image directory location
• file directory location
• use of headings (depth and correct usage)
• use and syntax of anchor ids
• use of external links
• template structure
• use of xrefs

I am probably leaving some others, but you get the picture.

If teams don't confirm to these mandates when they are rewriting their docs, then we shouldn't consider those docs modularized. Otherwise, 2 years from now, we will have multiple doc sets, written in their own vision and interpretation of what modularization is.

This is a great time to do this as many teams are putting a lot of time and energy into ripping old documentation and starting anew. Why not set some mandatory standards in place to make this job easier and consistent across teams?

Looking at https://redhat-documentation.github.io/modular-docs/#reusing-modules, the text recommends that

"When you create content in modules, you can use the same module multiple times in an assembly without having to replicate information in multiple source files. However, in order to facilitate module reuse, you must embed a document attribute variable in the anchor name for the module and then define that variable in the assembly each time the reused module appears. If the variable is not embedded and assigned, an error appears at build time reporting the duplicated anchor ID."

Shouldn't then the use of the variable be made mandatory for any new content by specifying it in the AsciiDoc Markup Conventions? https://redhat-documentation.github.io/asciidoc-markup-conventions/.

If I (working in OpenShift docs) want to include a module from the OpenStack docs, and those docs don't have the variable (context) in the headers, the books will not build due to the above mentioned issue. I would then have to request the OpenStack team to modify the headers which will add layers of issues to the whole process.

If we mandate that all new attributes have the context added, this will make it easier for the future success of modular docs.

In the Modular Documentation Reference guide, a module is defined as "independent" and something that "does not depend on other documents" (https://redhat-documentation.github.io/modular-docs/#modular-docs-terms-definitions). In addition, the guidelines we've been given for the Module Library indicate that modules cannot have any external dependencies.

I think this guidance is a bit misleading and unrealistic. Rather than guiding writers to avoid all external dependencies, I think we need to realistically consider all of the external dependencies that naturally exist, and then investigate the possibility of enabling writers to enable/manage them in a way that does not threaten the independence and reusability of the module.

Consider the following potential dependencies:

• Attributes - Modules use attributes that are typically defined in an externally-referenced attributes file. In many cases (such as working upstream first), it is not possible to include in the module the reference to the attributes file. Even if it is possible, it's still an external dependency on a document outside of the module.
• Images - Any module that includes a diagram, screenshot, or any other type of image has an external dependency on that file.
• Includes - While modules should not include other modules, and while fragments (aka, snippets) are best avoided whenever possible, they are nonetheless sometimes necessary. When working upstream-first, it is sometimes necessary to use snippets to include upstream-only content that, when brought downstream, can be replaced with a downstream-only snippet containing the downstream-only text. Without using snippets in these cases, the modules would not be reusable between the upstream and downstream. (Note also that any prohibition on using includes in modules also, by definition, prohibits us from using images in modules.)
• Links - for cross-references, using links instead of xrefs still introduces an implicit external dependency. AsciiDoc link syntax does not provide a mechanism for transcluding the title of the module being cross-referenced, which means we must manually enter the title of the module that is the link target. This adds a dependency on the target module's title; if that title should ever change, the link text in the cross-reference will be incorrect.

I marked this issue with the "Discussion" label in order to start the discussion. Perhaps a configuration file could be implemented to manage all of the above dependencies externally from the modules. Or maybe we would need a different type of mechanism altogether. Or perhaps I've misread things, and some of the above dependencies are not issues at all. In any case, I'd like to learn which dependencies we actually have in our modules, and how we might address them.

At the top of the Assembly template there is a comment that reads:

// Save the context of the assembly that is including this one.
// This is necessary for including assemblies in assemblies.
// See also the complementary step on the last line of this file.

It's very confusing. What does 'Save' mean here? I recommend rewording this but I don't have a recommendation because I'm not sure what it means right now.

See my pull request for details. I made additions and changes per my presentation and subsequent team discussion on standardizing anchor names, file names, and document attributes to enable content reuse and instill consistency across CCS.

There is no clear guidance as to inserting prerequisites into assemblies or modules. If I have an assembly with multiple modules, do I have to include the prerequisites in every module, or is it enough to include them once in the assembly?
How does this reflect the concept that every page is page one? What would our customers prefer? Are multiple occurrences of the same prerequisites bothersome as long as the customer portal does not offer topics (as opposed to 'books')?
I feel that we need more solid guidance in this area.

There are two identical pairs of directories in the repo:

• modular-docs-manual/common-content/
• /common-content/

and

• modular-docs-manual/images/
• images/

I suspect that the first listed used to be symlinks, but the someone got confused, copied them over, the change got merged, and no one noticed...

As we only have one doc in this repo, there's no need for symlinking.

The repo contains a bunch of files that are only relevant for downstream RH processes (/scripts/buildGuides.sh, modular-docs-manual/docinfo.xml, etc.). These need to be removed.

• (Some) writers don’t understand the need for [#id-{parameters}].
• The mod docs initiative has been asked (by the AsciiDoc Mark-up Conventions init.) to provide a doc that would explain the benefits of this approach and how it works.

I believe that the overall consensus so far was that the title, ID, and the file name should be the same when file name should include also the type of the module (procedure_<title>.adoc, concept_<title>.adoc, reference_<title>,adoc).*

There are a couple of challenges with this approach:

1. The file names can become really long (IMHO not a problem, consistency is more important)

2. Some file names that are reused and their title is different based on conditions cannot adhere to this rule. For example this file: https://gitlab.cee.redhat.com/red-hat-ceph-storage-documentation/doc-Red_Hat_Ceph_Storage_3-Container_Guide/raw/master/modules/procedure_updating-ceph-clusters-to-a-new-version.adoc

We should have an exception for these cases.

Thoughts?

• Ceph team uses also "assembly_<title>", not sure if it is necessary, though, thoughts?

As it was explained to @VladimirSlavik by AsciiDoctor developers[1], IDs must always be surrounded by double quotes in AsciiDoc because single quotes are markup.

The problem manifests, for example, when there is a double dash in an ID:

• When written as id="x--y", everything works as expected, and the resulting ID is x--y.
• When written as id='x--y', the double dash is converted to an en-dash (x–y), breaking the ccutil build.

Templates should be edited to replace single quotes with double quotes in ID.

[1] asciidoctor/asciidoctor#2960

The current assembly template is missing a way to preserve the parent context. Therefore, if you use the current template and set a context for an assembly as the template guides you to, any subsequent non-assembly includes will inherit the assembly's context, even if they're not in that same assembly. For example, if your master file has these includes:

master.adoc
├── assembly_foo.adoc
├── assembly_bar.adoc
└── reference_foo.adoc

The first assembly sets its context, and so does the 2nd, so the 1st assembly's context ends as it should because it's overwritten by the 2nd. However, modules don't set their own context (that's the point), and so reference_foo.adoc inherits context from assembly_bar.adoc, which we don't want because it makes it potentially very difficult to determine how to link to it from elsewhere.

The way to avoid this is to save the parent context into another attribute before setting the assembly's internal context, and then reset it back using the other attribute at the end of the assembly. So the structure should look like this:

:parent-context: {context}
//Saves the context of the parent to another variable
[id='assembly-title-{context}]
//Sets the assembly ID - still with the parent's context
= Assembly title
:context: assembly-context
//Sets context for anything included inside this assembly

Assembly intro

include::modules/foo.adoc[leveloffset=+1]
include::modules/bar.adoc[leveloffset=+1]

:context: {parent-context}
//Resets the context to what it was before the assembly's inner context was defined, so it doesn't "spill over" to any other parts of the title

We tried to follow this documentation and use the templates for documentation in our project Strimzi. However, we have run into problems with the assembly template. The template suggests that on the beginning of every assembly, we should save the parent context:

:parent-context: {context}

And restore it at the end of every assembly.:

:context: {parent-context}

However, the template suggests that every assembly should use the same variable parent-context. And this works only on a very flat structure. Once you change the context on two levels you can very easily mess up the context for all the upper levels because the original context will be never restores.

As an example, you can check these two samples:

• Using an old template: https://github.com/strimzi/strimzi-kafka-operator/tree/modular-docs-parent-context/documentation/test
• Using the latest template: https://github.com/strimzi/strimzi-kafka-operator/tree/modular-docs-parent-context/documentation/test2

Just check these out and open them in your editor / render them and you will see how the context is never restored properly.

So far the solution we used in our docs was:

1. Remove every parent-context
2. When the context is actually changed, save and restore the context, but always use the different variable to not override the other parent contexts

Can you please clarify if we are using it incorrectly or if it is a bug?

The following attributes should be added to the doc:

:toc: left
:toclevels: 3
:numbered:
:sectanchors:
:sectlinks:
:experimental: