URL shorteners in Red Hat product docs: to use or not to use

[bburt-rh]

Currently, because the SSG doesn't provide guidance for using URL shorteners in Red Hat product docs in the SSG topic about links and hypertext, we default to following the IBM Style guidance for using URL shorteners, which specifies allowed services and best practices.

I'd like to open up a discussion to address the following questions: Should we be using URL shorteners in RH product docs at all? What are the pros and cons? Should we just follow IBM Style guidance? Or not?

If we allow URL shorteners, what services should we recommend? Do we use the ones recommended in the ISG or, say, the official RH URL shortening service only, or some combination of the two? If we deviate from the IBM Style guidance at all, we would need to update the SSG topic about links and hypertext.

If we do not allow URL shorteners, we should update the SSG to say so, because right now, IBM Style says that it's OK, so currently this is our official guidance.

Thoughts?

[bergerhoffer]

IMO URL shorteners always seem risky. I personally don't like clicking links that were from URL shortener sites unless I really trust the source.

Since we don't often write bare URLs in our docs, I don't see a reason why we would need to use them.

I would vote for avoiding the use of shortened URLs in our product docs.

[bburt-rh]

I agree with @bergerhoffer that using URL shorteners in product docs could feel risky to our users -- even if it is an official RH shortened URL. For this reason, I think that the SSG should deviate from the ISG and tell writers to avoid using shortened URLs in nearly all circumstances in the product docs.

In my experience, this issue doesn't come up frequently in our product docs, so I think adding this guidance would be a low impact change.

[aireilly]

Unless there is a specific use case for the short url, I would tend to agree - don't use them in product docs.

[mportman12]

@bburt-rh do you have an example of bare URLs in product docs? I'm not sure whether the question of using shortened URLs would even come up enough in product docs to make adding guidance to the SSG worthwhile.

[mmuehlfeldRH]

I agree that we should not use URL shorteners in guides. However, I had some cases where my docs were linked in the product and, due to necessary changes in the guide structure, the URLs changed. This caused that they had to fix the link in an update. In thise case, a link shortener has the benefit that it's possible to adjust a link, if needed.

[sbmetz]

Sounds like a consensus that we'd like to avoid using shorteners, as we don't use bare URLs as a rule. The only reasons the issue would come up for RH writers is if they see the topic in the ISG, or wonder about the red.ht URLs we see with marketing-related content. @mmuehlfeldRH -- your use case sounds like a call for a redirect rather than a shortener, maybe?

[mmuehlfeldRH]

@sbmetz a redirect is also an option but requires a ticket, while you can update the shortened link in MO hub on your own. I have no strong preference.

[sbmetz]

True, and no strong preference on my side, either. For the SSG, I think we're OK saying don't use shorteners in customer docs. I wouldn't think links in products are in our scope.

[bburt-rh]

I agree with @sbmetz that it won't hurt anything to say not to use URL shorteners in RH product docs. Doing so would head off any confusion that the ISG guidance might cause.

Let's discuss next steps in the next meeting of the Style Council.

[bergerhoffer]

Update from the March 27 SSG meeting: Agreed that we should add guidance to the SSG about not using URL shorteners in product documentation. @bburt-rh to open a PR.

[Srivaralakshmi]

@bburt-rh any updates on this?