Prerequisite guidance needed

[yzimmerm]

There is no clear guidance as to inserting prerequisites into assemblies or modules. If I have an assembly with multiple modules, do I have to include the prerequisites in every module, or is it enough to include them once in the assembly?
How does this reflect the concept that every page is page one? What would our customers prefer? Are multiple occurrences of the same prerequisites bothersome as long as the customer portal does not offer topics (as opposed to 'books')?
I feel that we need more solid guidance in this area.

[adahms]

Thanks for raising this issue, @yzimmerm!

This topic has been generating quite a lot of discussion - elsewhere, if not directly here - but I have yet to hear a definitive answer.

Whenever I think about this problem, the example I keep coming back to is creating a virtual machine in RHV and the steps that would be involved there.

In my mind, a task like this would be a 'supertask' or assembly where the individual procedures make the most sense when run in a sequence - which makes them a perfect example of an assembly - but can also be run individually.

For example, you can create a virtual hard disk in RHV but not attach it to a VM, and you can create a VM and not assign a network interface, but if you want to go from having nothing and end up with a running VM, you probably want to do them all.

In that case, the assembly prerequisites would call out that you need a working data center and storage domains, etc. but the individual procedures would only call out what needs to happen immediately before that rather than leading up all the way to it.

I'd love to take a look at a few more concrete examples and see how this might apply to them, but does such a 'minimalist' approach to prerequisites sound like it might work?

[rkratky]

@adahms, what you describe could also be called the common-sense approach. IOW, prerequisites only need to describe what's immediately necessary (for the unit at hand).

[adahms]

Thanks @rkratky - it might be getting a bit redundant to ask as much, but to make sure I don't miss any nuances, does that sound like the approach we should be taking?

It sounds like a few people could do with having this explicitly stated, so this would make a good candidate for a start on 'best practices' or even as a general addition to the guidance.

[bobjohnsrh]

I agree that prerequisites are specific to the module. That is how I have always implemented them.

Andrew's example of a "supertask" or process is the most common situation in which I have encountered prerequisites for a set of tasks. Options are to document the prerequisites as prerequisites for the supertask, or as prerequisites to the first procedure in the supertask. There are good arguments for both approaches. I would tend to recommend making documenting the prerequisites in the first procedure in the supertask, as that is more proximate to the user actually performing the procedure. Moreover, some users might skip the supertask and go straight to the first procedure, therefore missing the prerequisites.

If any prerequisite is specific to a particular procedure (rather than general for the procedures in the supertask), I have always documented with that procedure, not as part of the supertask.

A less common situation that I have encountered is a set of parallel procedures. While it is tempting to document prerequisites in a parent container for the parallel procedures so you only have to document the prerequisites once, it is not a great option for effective modular content. If you have a pointer (thus introducing a dependency), that is extra clicks for the user to find all the information they need to perform the procedure. If you don't have a pointer, the user may not be informed about the prerequisites. Better practice is to include the prerequisites in each procedure, even if you are repeating content.

[emmurphy1]

For some reason, this is clear to me. If a story has prerequisites, list them at the top of the assembly. If a module has prerequisites, list them at the module level. The biggest recurring issue I find when I'm peer reviewing modules is a lack of context, often caused by the omission of prerequisites. Granted, this does create repetition and I acknowledge that repetition conflicts with minimalism principles, but as I believe @tradej pointed out elsewhere, users often scan our documents so repetition isn't always a bad thing. For me, the goal is clarity.

[Preeticp]

When we add the clause that you can not use xrefs in modules, having a consolidated Prerequisites section in the assembly, for all the modules in the Assembly, with links, and adding prerequisites relevant only to a particular module, to that module, without links, makes sense to me.

[yzimmerm]

See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_virtualization/getting-started-with-virtualization-in-rhel-8_configuring-and-managing-virtualization#creating-vms-and-installing-an-os-using-the-rhel-8-web-console_assembly_creating-virtual-machines. In this guide, every procedure that uses the web console includes the prerequisite of having installed the web console virtualization plug-in. Yehuda Zimmerman, RHCSA Technical Writer III Red Hat EMEA <https://www.redhat.com/> yzimmerm@redhat.com M: +972-50-942-1156 IM: yzimmerm <https://red.ht/sig>

…

On Wed, May 20, 2020 at 12:28 AM Rolfe Dlugy-Hegwer < ***@***.***> wrote: @yzimmerm <https://github.com/yzimmerm> It seems like the guide <https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules> answers some of your questions in the "Procedure Prerequisites" and "Assembly Prerequisites" subsections. There are many thoughtful replies in this thread. It might help for us to cite real-world examples to emulate or avoid. Ideally, our examples should include links to both the source and the output so the reader can understand prerequisites in the context of an assembly and its modules. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#97 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG67PVLLA27WS75CHMWBCADRSL2ZHANCNFSM4HJS374A> .

[rolfedh]

@yzimmerm How would you apply the "Procedure Prerequisites" and "Assembly Prerequisites" subtopics in the guide, and the above advice, to the example you've shared?

[yzimmerm]

Well, I actually wrote the example. Because every page is page 1, the prerequisite must be included for every procedure. We cannot assume that someone has even seen the assembly. So I would say that only an assembly that contains a procedure (such as an assembly which otherwise would have only a single procedure module) in it must have the prerequisite for the procedure. Yehuda Zimmerman, RHCSA Technical Writer III Red Hat EMEA <https://www.redhat.com/> yzimmerm@redhat.com M: +972-50-942-1156 IM: yzimmerm <https://red.ht/sig>

…

On Wed, May 20, 2020 at 3:17 PM Rolfe Dlugy-Hegwer ***@***.***> wrote: @yzimmerm <https://github.com/yzimmerm> How would you apply the "Procedure Prerequisites" and "Assembly Prerequisites" subtopics in the guide <https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules>, and the above advice, to the example you've shared? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#97 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG67PVOKWWU53U5ETDAZPIDRSPC3ZANCNFSM4HJS374A> .

[rolfedh]

@yzimmerm Nice example. How would you improve the guide to answer your original set of questions?

[yzimmerm]

Well this is exactly my issue. I *have* to include the prereqs everywhere, because every page is page 1! It's just annoying. And the guidelines are not that clear. Yehuda Zimmerman, RHCSA Technical Writer III Red Hat EMEA <https://www.redhat.com/> yzimmerm@redhat.com M: +972-50-942-1156 IM: yzimmerm <https://red.ht/sig>

…

On Wed, May 20, 2020 at 5:57 PM Rolfe Dlugy-Hegwer ***@***.***> wrote: @yzimmerm <https://github.com/yzimmerm> Nice example. How would you improve the guide to answer your original set of questions? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#97 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG67PVPGQPN75YJXZULR6O3RSPVV7ANCNFSM4HJS374A> .

[IngridT1]

@rolfedh The idea of every page is page one comes from a very influential book:
https://everypageispageone.com/the-book/

I imagine Yehuda is referring to that.

[yzimmerm]

It was stressed by Christy in the mod docs training (if I remember correctly). Yehuda Zimmerman, RHCSA Technical Writer III Red Hat EMEA <https://www.redhat.com/> yzimmerm@redhat.com M: +972-50-942-1156 IM: yzimmerm <https://red.ht/sig>

…

On Sun, May 24, 2020 at 5:53 AM Rolfe Dlugy-Hegwer ***@***.***> wrote: Mark Baker, the author of EPPO, has an interesting post on his blog called There are no Prerequisites <https://everypageispageone.com/2014/07/14/there-are-no-prerequisites/> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#97 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG67PVOCOF7SDFWQ77THSEDRTCDZBANCNFSM4HJS374A> .