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

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

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

Closed emmurphy1 closed 4 years ago

emmurphy1 commented 4 years ago

https://github.com/redhat-documentation/modular-docs/issues/126

In addition to adding the _abstract and _additional-resources tag, this change includes a second set of templates with comments removed. I have also updated some of the explanations.

msuchane commented 4 years ago

I've noticed several different changes in this PR:

Pantheon 2 metadata have been added.
Abstracts now explain the Pantheon 2 metadata.
Module IDs now have module type prefixes, but the assembly ID stays without a prefix.
The Prerequisites heading now says Prerequisites (optional).
The example items under Additional resources have changed.

Are all of those required for Pantheon 2? If not, wouldn't it be better to create separate pull requests for the metadata and the writing changes so that the metadata can be reviewed quickly and we can spend more time on the writing style discussion?

rkratky commented 4 years ago

second set of templates with comments removed

@emmurphy1, I think this creates unnecessary overhead (maintaining two sets of templates). I suggest the following:

Reformatting all multi-line comments in the templates to use the //// (four slashes) delimiters, which will allow text editors to collapse the comments, thus easily hiding them if users find them distracting.
Promoting the use of newdoc, which can automatically create pre-populated templates, which can be, optionally, without comments -- thus giving you the same result you're submitting here.

sterobin commented 4 years ago

@emmurphy1 I confess that in my haste I focused on the changes and didn't even register your explanation (or new file names) that you were duplicating the templates without comments. In that case, I agree with @rkratky and would go with one of his suggestions. Or leave an instruction to writers saying that they can generate their own non-commented version using one of those options. I just think we shouldn't worry about taking that burden upon us (FCC) to come up with the comment-free templates. Can be left to the writer in these ways, imo.

emmurphy1 commented 4 years ago

@sterobin @rkratky I removed the uncommented comments and added //// as suggested.

msuchane commented 4 years ago

I've reviewed the changes once more and I'm happy with the PR. I've added two comments about issues that I consider just cosmetic.