search

redhat-documentation / supplementary-style-guide

This project maintains the Red Hat supplementary style guide for product documentation that supplements the IBM Style guide
https://redhat-documentation.github.io/supplementary-style-guide/
Creative Commons Attribution Share Alike 4.0 International
34 stars 74 forks source link

Add a link to the IBM Style Guide #490

Closed mmcclaingithub closed 2 months ago

mmcclaingithub commented 3 months ago

It would be helpful to have a link to the IBM Style Guide (ISG) in this this guide. It will be more efficient to be able to click a link in this doc when we need additional style information from the ISG.

bergerhoffer commented 3 months ago

Hi @mmcclaingithub, we purposefully don't include links to the IBM style guide. The SSG is a completely open, public guide. We don't include any internal only links in the SSG for this reason. And the IBM Style guide is not public - you must have IBM or Red Hat credentials to access it.

mmcclaingithub commented 3 months ago

We could specify the need for credentials. As an SSG user, I often don't find what I am looking for and need an easy way to access the IBM Style Guide (ISG). We mention the ISG, so seems reasonable that we'd offer a quick way to access it--especially if it is deemed supplemental.

Is the SSG supplemental to something other than the ISG?

bergerhoffer commented 2 months ago

@redhat-documentation/ccs-style-council any other thoughts on including a link to the ISG in the SSG? I don't remember all the details back when we discussed including or not including the link.

dayleparker commented 2 months ago

I love this idea @mmcclaingithub - just a single link as 'additional references' to IBM Style (with a note about needing to authenticate as mentioned) would be sufficient. We did this in the HCC guidelines by adding a Related documentation section to make it easier to jump back and forth. https://docs.google.com/document/d/17e9ZDpIxv0ncv4hskRQ9AsU6sfcxcrsI4xpxj0Q6oCg/edit#heading=h.k899k2lix75r

bergerhoffer commented 2 months ago

Discussed this at the 31 July SSG meeting. We agreed to update the SSG to add in a link to the ISG.

I will take care of opening the PR for this. Consider also a general update that some links may not work for non-Red Hatters, and also about how to authenticate to the ISG with your RH credentials.

bergerhoffer commented 2 months ago

PR: https://github.com/redhat-documentation/supplementary-style-guide/pull/509

bergerhoffer commented 2 months ago

@mmcclaingithub can you please review the PR to see if this is what you were hoping for? I added the link a few places, but we don't necessarily want to add a link to it every time it's mentioned.

https://github.com/redhat-documentation/supplementary-style-guide/pull/509

bergerhoffer commented 2 months ago

This PR was merged, so closing this issue!

ISG links are in a few places in the intro: https://redhat-documentation.github.io/supplementary-style-guide/#_about_this_guide

mmcclaingithub commented 2 months ago

@bergerhoffer Thanks! Sorry, I did not see the request to review until now.