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/> [email protected] 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/> [email protected] 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/> [email protected] 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/> [email protected] 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> .

[rolfedh]

Mark Baker's Every Page is Page One (EPPO) and There are no Prerequisites
do not recommend repeating prerequisites.

Our Modular Documentation Reference Guide (MDRG) does not require or recommend repeating prerequisites in every module:

• For assemblies (pages) the MDRG says:
  • "Optionally, an assembly can also include prerequisites and additional resources."
  • "Prerequisites are conditions that must be satisfied before the user can start following the assembly."
• For a procedural module (page section), MDRG advises authors to "focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites."

Nonetheless, I think @yzimmerm raises some crucial issues, which I've paraphrased here:

• Where do I place prerequisites in assemblies and modules?
• How do I apply EPPO's best practices to modular documentation?
• How do customers use our product documentation? What works and what doesn't?

I think we can help authors of modular documentation by answering these questions. So I've created a pull request with placeholder files for an FAQ. This PR is a preliminary step to help us answer these questions collaboratively. I don't expect that this FAQ will be merged into the guide as is or at all. It will undoubtedly require some discussion and work to become ready. If it doesn't fit in the MDRG, there are other venues where we might publish the same content.

Please let me know if you're interested in working on these topics with me.

[rolfedh]

First draft. Please feel free to comment.

[IngridT1]

@rolfedh, There are no Prerequisites by Mark Baker is excellent, and definitely something that we need to think about as a team. We may not be able to eliminate them every time, but I feel like that article is something that everyone should read. Thanks for sharing.

[emmurphy1]

Nice start, @rolfedh . @oraNod has volunteered to create an FAQ described in issue 3. Don, Rolfe has made a start on this. Please look at his pull request.

[rolfedh]

@emmurphy1 Issue #3 is about creating a mod doc template for FAQs, not an FAQ about mod docs. @oraNod, if that's what you want to do, please go ahead.

I'm in heads-down mode preparing for a major release in the next two weeks. I've done a lot of thinking on this Issue #97 after creating the pull request for it. I have some major updates to make to this proposed prerequisites guidance, but don't have the time to go into it right now. @oraNod if you're thinking about prerequisites, would you mind holding off until the second or third week of August?

[oraNod]

@rolfedh I think there has been some miscommunication. I'm not interested in #3 but have an eye on #75

[Preeticp]

Another point that came up within the OpenShift team discussion was if we want to use Prerequisites as second level headings (==) instead of the .Prerequisites we use currently. @kalexand-rh could probably provide more context on this.

[ncbaratta]

Another point that came up within the OpenShift team discussion was if we want to use Prerequisites as second level headings (==) instead of the .Prerequisites we use currently. @kalexand-rh could probably provide more context on this.

I would be very against this, mainly because we have so much of our documentation modularized already with the label format instead of the heading format and it would require extensive edits to make us all consistent this late in the game.

[mjahoda]

@ncbaratta Just a note that @msuchane managed to convert the whole rhel-8-docs repository from discrete headings for Prerequisites and Procedure to the initial full-stop notation recently. I believe that the opposite direction is also possible in an automated way but I do not advocate for doing this.

Furthermore, I am not sure if I recall it correctly but we had a discussion thread in which someone pointed out that the discrete headings are better from the accessibility perspective (for visually impaired people using screen readers, specifically).

[rolfedh]

Hi @kalexand-rh. What are the proposed reasons for making Prerequisites a section title (heading)?  
From the conversation I heard, it sounded like it was so one could link to prerequisites within a topic.
If so, would placing an Explicit id above .Prerequisites work instead?

[bobjohnsrh]

From an accessibility perspective, I would recommend against using a second-level heading for prerequisites.

Users on screenreaders often browse pages from heading to heading, and the heading level is meaningful in establishing the organization of the document. The second-level heading approach would always define the Prerequisites at the same level, regardless of the location of the containing module. The screen reader user would thus lose the context of the heading, and it would no longer be clear that the prerequisites are part of the module. Navigation of the headings would also be disrupted.

[mjahoda]

From an accessibility perspective, I would recommend against using a second-level heading for prerequisites.

A second-level heading in a module is a third-level heading in an assembly.

After a discussion with @vpolasek, I have recalled what the problem is.

.Procedure is rendered as <p class="title"><strong>Procedure</strong></p> on the Customer Portal at the moment

[discrete]
== Procedure (or Prerequisites) is rendered as <hX>Procedure</hX> depending on the leveloffset.

[rolfedh]

@Preeticp @ncbaratta @mjahoda @kalexand-rh @bobjohnsrh I've created a separate issue to handle the question of "assembly-level prerequisites" you've raised here: #124
Please continue our discussion of "assembly-level prerequisites" there.

[rolfedh]

After reviewing our conversations, I've decided that the additions I was proposing in #117 were too lengthy and too far off the mark. Therefore, I've closed that PR.

[yzimmerm]

Once we will be using PV2 for the documentation on the portal, going forward, there may be customers who open modules from the search and never see an assembly. These customers will never see the prerequisites if they are not included in each module. As a result, I feel that we MUST include the prereqs in the modules.
However, I understand that this does not look great and may get cumbersome.
Solution idea: let's publish the documents with the prerequisites (and perhaps additional resources) as icons that pop-up sub-windows to display the prereqs on the page.
This way the customer will determine if he needs to see the prereqs and can easily pull them up, without having them be overly distracting.

[mikemckiernan]

Can this issue be closed?

The guidelines indicate that prerequisites are presented before the procedure.