Diverging from the templates

[oraNod]

I'm working on setting up a set of modular docs from scratch. During different peer reviews, I've got feedback that can be summed up as "you must follow the templates". More specifically that my procedural topics should contain the .Procedure markup directly before the first step.

The benefit of keeping it is consistency across the doc set. These sort of visual cues in the docs help train users to navigate the content and find info.

I get all that. I'm not arguing against it.

My contention is that including the same markup in all procedures doesn't always work. Maybe not all procedures are created equally.

Does the procedure form part of an installation process?

Is the procedure part of a more tutorial-style assembly?

In lots of more tutorial-style content, assemblies can become almost ordered lists themselves. Users often don't need that much context in each procedure and, from a minimalism perspective, the less we can put in the user's way, the easier it is for the user to get something up and running.

In middleware that is often where users come from, app developers want to get stuff running. Docs should be lightweight and task-based, almost like cheat sheets or quick reference for specific tasks.

Consider the following assembly:

[id='spinning_up_clusters']
== Spinning Up {brandname} Clusters
:context: spinning_up_clusters

You create {brandname} clusters from custom resource definitions.

[id='creating_minimal_clusters-{context}']
=== Creating Minimal {brandname} Clusters
include::topics/proc_create_cluster_minimal.adoc[]

[id='verifying_clusters-{context}']
=== Verifying {brandname} Clusters
include::topics/proc_verify_cluster.adoc[]

Each topic in the preceding assembly contains one or two steps:

Short intro text for #context. 

. Create a {brandname} cluster with two nodes.
+
----
$ oc apply -f {operator_raw}deploy/cr/cr_dg_minimal.yaml
----
+
. Verify that the {ispn_operator} creates the pods.
+
ifndef::productized[]
[source,options="nowrap"]
----
$ oc get pods -w
----

Including the .Procedure markup results in output that is somewhat noisier than it needs to be if you're working on content that is designed more as a tutorial or quickstart.

Following the principles of minimalism, anything that adds noise gets the knife.

[sjay72]

I posit that a Tutorial is a potentially different type of module from a Procedure and should be labeled as such for consistency. What's the difference? This is off the top of my head, not proposing "official" definitions:

• Procedure - non-prescriptive, the steps of the procedure contain variables, for which the user substitutes values that are specific to their environments. By following the steps, the customer achieves a task in their environment - they actively create or change or [enter verb here] something.
• Tutorial - prescriptive, the author is supplying users with exact commands and values to use with the goal of learning, not necessarily actively creating or changing or [verb here] their environments; the activity occurs in a controlled space. It results in a sample something that may not be actually functional in their env. After the learning experience, the user would have to perform the actual procedure, supplying information specific to their envs to actually change it.

If some of your assemblies are procedure-focused and some are tutorials and neither contains a "noisy" label or easy cue, how does one set expectations for the user? Explanatory text in prose formal is less minimal than a one- or two-word heading.

In terms of content re-use across products, it's important for reusers to understand the kind of user experience created by mixing assemblies that contain procedure- or tutorial-type content.

[pwright]

Is 'Boiling potatoes' a tutorial or a procedure? You might read it with carrots in your hand, and consider it a tutorial, that it was prescriptive about the vegetable, but I can make the substitution. Or you could say that the whole thing should be rewritten as 'Boiling vegetables' and really make it 'non-prescriptive'. Not saying it's right, but most of our (mobile) procedures are leaning towards 'tutorials'. Why? because the designers think we should just publish reference material, and getting commitment to any task oriented docs is a win.

[oraNod]

Thanks for the interesting take @sjay72

"Explanatory text in prose formal is less minimal than a one- or two-word heading." This is true. In some of my "tutorial-style" procedures there's often no contextual intro.

= Doing the Procedure 

. Complete step 1.
. Complete step 2.

I'll go back to my earlier comment that assemblies can be like ordered lists. In some tutorial-style assemblies, you could even put the context in just the assembly.

[rkratky]

@oraNod, you're forgetting one important principle: every module (unit of content) should be capable (readable, understandable) on its own. In other words, we follow the rule "every page is page one". Since we cannot control where the user lands in our docs, we need to make sure that there's enough context provided, so that the respective module can function as 'page one'.

This is also important for reusability. If your modules cannot be reused in other assemblies or cannot stand on their own, then they should not be modules :)

[oraNod]

@rkratky "every page is page one" is a problematic rule.

I get that modules/topics are logical units of content that can stand on their own. and I don't think adding extra things, such as .Procedure, adds enough meaning to help modules stand independently. imo it's just a visual cue that helps with consistency/uniformity. that can be a good thing but, in some cases, it can also detract from the overall usability of the doc.