Remove == Next steps as option for assemblies

[bergerhoffer]

I chatted with @jhradilek about == Next steps being flagged by the vale rules for DITA migration. Because only == Additional resources are allowed in assemblies after module inclusions.

He said that the rule was correct, and that we'd need to remove (or move) any == Next steps sections in assemblies before migration.

Requesting that we update the mod docs guide to reflect that next steps in assemblies are no longer valid. Happy to draft a PR for this if it helps.

[jhradilek]

To expand on this, the presence of == Next steps is not a problem on their own, the section is not going to be dropped during conversion. It is the location it is at that is going to chance, which depending on how you intend to present the information may be undesirable so AsciiDocDITA vale gives you a fair warning about it.

Consider the following assembly.adoc file:

:_mod-docs-content-type: ASSEMBLY

= Assembly title

Assembly introduction.

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

== Next steps

. Next step.

== Additional resources

* link:https://example.com[An example link]

This file includes one module and intends to follow it by two sections: Next steps and Additional resources. The contents of the included concept.adoc file is as follows:

:_mod-docs-content-type: CONCEPT

= Concept module title

Concept module contents.

When converting this to DITA without re-splitting the contents, that is, retaining the 1:1 mapping between the original AsciiDoc and converted DITA files, this can only be expressed in the DITA map as follows:

<topicref href="assembly.dita" navtitle="Assembly title">
    <topicref href="concept.dita" navtitle="Concept module title" />
</topicref>

What you probably expect to see after the conversion is the following:

Assembly title

Assembly introduction.

Concept module title

Concept module contents.

Next steps

1. Next step.

Additional resources

• An example link

But because of the way that DITA map has to be constructed, all contents previously present in assembly.adoc stays with assembly.dita and the output therefore looks as follows:

Assembly title

Assembly introduction.

Next steps

1. Next step.

Additional resources

• An example link

Concept module title

Concept module contents.

I hope this helps explain the reasoning behind the warning.

[bergerhoffer]

@jhradilek Yes that makes sense to me. But just want to confirm - are you in agreement that we should remove next steps as part of the assembly template? Or do you think we should keep it as is?

[jhradilek]

My preference would be removing it from the assembly templates.

[bergerhoffer]

Great thanks! @emmurphy1 let me know what you think!

[mjahoda]

Even if we don't have Next steps, the order of Additional resources before includes looks weird to me (if I understand #248 (comment) correctly). Anyway, if there is no way to place Next steps elsewhere than right after an assembly introduction, I support the proposal. I can also submit a PR to address the issue if we agree on this.