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
82 stars 68 forks source link

Change format of Additional Resources/Next Steps to bulleted links only in the templates #135

Closed emmurphy1 closed 3 years ago

emmurphy1 commented 3 years ago

For the Additional Resources or Next Steps sections in the assembly, concept, and procedure modules, currently some writers provide lead-in text and some writers provide just links:

Additional resources

Additional resources

NOTE: In PV2, anything under Additional Resources or Next Steps (tagged with the new 'addtional-resources' tag) will appear in a box under the module headed Related Content. However the PDF will have the heading in the source file (Additional resources or Next steps).

rkratky commented 3 years ago

@emmurphy1, I believe this should be left to the writer to determine what's best for their particular case. In other words, let's only add this as a non-binding recommendation.

While I agree that oftentimes, links alone suffice (and are easier to parse when quickly scanning the content), there are cases where some context is called for. For example, when adding a link to a resource whose connection to the matter at hand is not immediately obvious (i.e. not apparent from the title of the linked content), it's useful to include a note about.

So, if the module in question is called Configuring XYZ, then it makes no sense to say:

Here, the prefixed "context" is redundant.

However, when linking to something else, it's a different story:

Here, the context makes sense, IMO.

emmurphy1 commented 3 years ago

Conversation carried over from PR 130:

rolfedh 13 days ago •

"X is installed. For information about installing X, see " contains redundant information and surplus words :-). We could simplify this by converting the prerequisite into a link. The link text should state the prerequisite, not the title of the topic.

Suggested change

The proposed format is also more consistent with the new "Additional resources"

@emmurphy1 emmurphy1 13 days ago Author Member OK, Well, I just thought I was giving a practical example. The focus of this PR is to get the attributes in so I've reinstated the original prerequisite guidance and we can look at this later if we want.

@stoobie stoobie 2 days ago Member @rolfedh @emmurphy1 I like brevity, but the "For information about" is important to provide context. It gives me a sense of security about what I'm clicking on. "X is installed" does not necessarily inform me that by clicking on it, I will go to a page that describes how to install X. Generally, a link to a document should include the title of the document. See Link text in the Google Developer Documentation Style Guide.

@rolfedh rolfedh yesterday •

@stoobie So you support saying, "X is installed. For information about installing X, see Installing X," for example?

@mrksu mrksu yesterday • Member My preferred way would be to drop "about installing X" because that's already implied by "Installing X", the label of the link. The result:

"X is installed. For information, see ."

@stoobie stoobie yesterday Member @rolfedh I agree with @mrksu. If it's under Additonal resources, I'm good with just the title of the target.

aburdenthehand commented 3 years ago

I agree with @rkratky breakdown up above. The way I see it we have three scenarios:

  1. xref: title contains sufficient context - no additional context necessary
  2. xref: title does not contain sufficient context - provide additional context
  3. link: external link should provide context to where the user is being directed (and likely follow ISG .153 Linking strategies as necessary) (Maybe we have more scenarios..) This can lead to situations in which we have a list of 'For more information about ....", or a mix of the above, under an obvious heading like "Additional resources", neither of which looks super rad, but I think that should fall under writer discretion for how best to handle given the situation. At a minimum I believe the user should always know why they would want to click on a link, and where they'll be directed to if it's external to the given doc.
rolfedh commented 3 years ago

I agree with @rkratky breakdown up above. The way I see it we have three scenarios:

  1. xref: title contains sufficient context - no additional context necessary
  2. xref: title does not contain sufficient context - provide additional context
  3. link: external link should provide context to where the user is being directed (and likely follow ISG .153 Linking strategies as necessary) (Maybe we have more scenarios..) This can lead to situations in which we have a list of 'For more information about ....", or a mix of the above, under an obvious heading like "Additional resources", neither of which looks super rad, but I think that should fall under writer discretion for how best to handle given the situation. At a minimum I believe the user should always know why they would want to click on a link, and where they'll be directed to if it's external to the given doc.

+1

emmurphy1 commented 3 years ago

The general consensus is that whether or not to provide explanatory text with an Additional Resources link should be up to the author. Christine Bryan created this ticket for the Pantheon 2 work: https://projects.engineering.redhat.com/browse/CCS-4121

emmurphy1 commented 3 years ago

In addition, lists of links without context can be problematic from an accessibility POV. I am closing this issue.