WIP: issues 160 and 155 updated the template ID and abstract instructions

[emmurphy1]

This PR includes issue 160 and issue 155.

[mikemckiernan]

/lgtm

[stoobie]

I support the changes that Robert is proposing, which remove some tooling or implementation-specific details. The revised suggestions help preserve the usability of this content for writers. For the id parameter, perhaps we should simply say that it should match the file name.

@rolfedh See issue 160. When I was using the template, it was not clear to me what technically comprises an abstract, and so I did in incorrectly. Where am I (or anyone) supposed to find this info?

Also, is the [role="_abstract"] tag not implementation-specific? If it is not, then what are the vanilla rules for this tag?

If you're not going to include some guidance here, then you need to provide it somewhere. How is anyone supposed to know how to do it?

[rolfedh]

I support the changes that Robert is proposing, which remove some tooling or implementation-specific details. The revised suggestions help preserve the usability of this content for writers. For the id parameter, perhaps we should simply say that it should match the file name.

@rolfedh See issue 160. When I was using the template, it was not clear to me what technically comprises an abstract, and so I did in incorrectly. Where am I (or anyone) supposed to find this info?

Also, is the [role="_abstract"] tag not implementation-specific? If it is not, then what are the vanilla rules for this tag?

If you're not going to include some guidance here, then you need to provide it somewhere. How is anyone supposed to know how to do it?

@stoobie, please see my response to these same questions above: https://github.com/redhat-documentation/modular-docs/pull/163#discussion_r631018633

The Mod Docs guide and templates do not cover requirements that are uniquely for PV2.

[emmurphy1]

@stoobie, @rkratky makes a very good point. With his guidance, we are trying to make the templates as independent as possible from Pantheon. Management asked us to include the abstract tags in the templates because they are essential to PV2 and do not interfere with other uses of the templates AFAIK. I agree that we need to give CCS folks more information about what PV2 expect under those tags. Perhaps the best place for that information is the PV2 Users Guide? WDYT. Note that I have updated the templates with Robert's suggestions.

[mikemckiernan]

I'll hazard my opinion. I've come around to thinking that the PV2 docs are the best place to cover the reqs that PV2 drives to source files.

For example, I find this req to specify the abstract very tedious and a poor use of human time. I proposed (and think it's in use) that PV2 just use the first para when the abstract attribute is missing--or intentionally omitted because there are more valuable things to do.

So, @stoobie, folks tuned into PV2 might know about a change like that one and might be in a position to update the PV2 docs to describe the PV2-specific req, but the mod-docs folks might not be in the information line-of-sight.

That's my opinion. It and a quarter will get you a phone call.

[emmurphy1]

@mikemckiernan AFAIK, the abstract tag is required by PV2. Although that might change in the future by one mechanism or another, right now it has to be there. Management requested that we include the tags in the templates because to not include them but instruct writers to add them would create confusion. I believe that @rkratky acquiesced to this compromise because the tag does not hinder non-Pantheon 2 users. I agree that if PV2 could identify the first para as the abstract without the tag, removing the tag would be ideal. Let's revisit this issue if the requirement changes.

[yzimmerm]

lgtm

[stoobie]

@emmurphy1 @mikemckiernan @rolfedh This is, in fact, something that we can mention in the Pv2 docs, and this is actually a good time for this.