search

redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
82 stars 68 forks source link

Add [system:abstract] to concept, reference, procedure templates #126

Closed bobjohnsrh closed 3 years ago

bobjohnsrh commented 4 years ago

In the CCS email discussion about short descriptions, Dawn mentioned that the first couple of paragraphs following the tag [system:abstract] will be processed specially by Pantheon 2.

The templates for the concept, reference, and procedure information types should be updated to include this tag before the text describing the short decription.

adahms commented 4 years ago

Thanks for raising this one, @bobjohnsrh!

Because this is a requirement specific to PV2, my understanding is that we'll be addressing this in the end-user documentation we're creating for that rather than the MDRG.

I'll leave the issue open for the modular documentation review board to comment on, but from my perspective, I'm aware of the need for us to document this, and will be looking to add this to the queue for the EUD folks as time allows.

bobjohnsrh commented 4 years ago

@adahms I'm concerned that it is easy to overlook this tagging if we document it rather than putting it in the templates.

If PV2 is the future, which is my understanding, why would the templates not reflect that future?

adahms commented 4 years ago

@bobjohnsrh - The modular documentation templates are intended to be a set of guidelines that carry no dependencies on any given tool or solution. As such, the direction has been to ensure that any requirements specific to PV2 go in the end-user documentation for PV2 rather than in the modular documentation templates.

It's an area of possible confusion, that's for sure, and we're discussing how best to both clarify this and ensure people get all the details they need. Tools such as newdoc could be a great way to strike a happy medium, as is some additional tooling and validation.

Unfortunately, I don't have a final solution for you today, but the program is aware of this and seeking a solution.

emmurphy1 commented 3 years ago

Folks, I've added the [role="system:abstract"], the syntax agreed by the engineering team in the Assembly Templates meeting, to a set of simplified templates. I also made updates to the explanations. Writers have often asked for templates that do not include the extensive comments. I propose that we provide two sets. When the changes to the simplified templates are approved, I'll incorporate those changes in the fully-commented templates.

emmurphy1 commented 3 years ago

So that addition resources can appear as 'Related Content' in the PV2 HTML, we nee to add the following tag above the .Additional resources tag in modules and == Additional resources in assemblies. I've added this to the templates.

emmurphy1 commented 3 years ago

@redhat-documentation/fcc-review-board I've updated the templates as a result of discussions in the Assembly Templates meeting. Please review and approve or add your comments. I created a new set of templates, almost without comments to make it easier for writers to see the structure. After these templates are approved I will update the commented templates as well.

I've been asked to expedite this. The new tags are required for PV2. We need to get this information out soon so that those groups preparing to publish on PV2 in the next few months can be prepared.

emmurphy1 commented 3 years ago

The templates have been updated.