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
80 stars 67 forks source link

Creating modules|Procedure modules contains unclear parts #200

Closed mjahoda closed 11 months ago

mjahoda commented 1 year ago

https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs

Procedure modules can also contain prerequisites, verification steps, and additional resources or next steps.

Does the previous sentence mean that we can have either additional resources or next steps, but not both?

If yes, then I am suggesting to allow both.

Moreover, the order of those parts is also not clear. For example, can I place next steps right after the procedure steps (when it makes sense in a particular procedure)?

emmurphy1 commented 1 year ago

@mjahoda the 'or' in that sentence means either one or the other. However, I won't object to changing it if the board agrees: Procedure modules can also contain prerequisites, verification steps, additional resources, and next steps.

If we decide on this change, I think Next Steps should be last and we should modify the example in the template to illustrate this. I am interested to hear what others think.

emmurphy1 commented 1 year ago

@mjahoda the change that you made in the pull request (https://github.com/redhat-documentation/modular-docs/pull/202/files) is different from what I understood this request to be. You have introduced a new element to the procedure. I think we need to discuss this further before proceeding with the change.

mjahoda commented 1 year ago

@emmurphy1 Unfortunately, I noticed your comment after I merged the PR #202. I hope that because it does not introduce any strict rule (rather the other way round), there is no harm to keep it merged until we discuss it further.

emmurphy1 commented 1 year ago

@mjahoda that's OK. @ncbaratta reverted it. Leaving it there would create confusion. I'll start a discussion on the Slack channel. I had it on the agenda to discuss at the last meeting but you were there.