Update citation format for direct quotations

[rclee33]

I suggest updating citations for the sources of direct quotations. It looks like most citations of this sort use a footnote. However, there is one exception, which uses a bracketed reference. The 4.2. Identifying and Avoiding Slang > Productize entry contains a direct quote followed by: [wiktionary].

For sources that the style guide quotes directly, I suggest shifting away from footnotes, as that format is less useful for readers of online content. Ideally, footnoted references should be replaced with in-line citations that readers can follow at their point of need within the text. Additionally, it would be helpful to provide some basic information about the source (such as the title) along with the URL. This practice gives important context for the source’s reliability, even if readers don’t actually access the URL. Developing more robust citations also helps model expectations around appropriate source use for anyone using the style guide as a resource.

Suggested fix: Since we’re not publishing formal academic prose, I don’t think we need to adhere to something like the Chicago Manual of Style for citations. I also think it’s okay if the citations in the style guide differ from those in RHT content, since the guide has a different context, audience, and purpose. Following the IBM style guide, we could update the citation format in the style guide to include work titles and embedded links:

Original: Always use a hyphen if clarity would suffer otherwise. For example, "He recovered his health" versus "He re-covered the leaky roof." ⁠[1] ...content excluded... [1] www.apstylebook.com

Update: Always use a hyphen if clarity would suffer otherwise. For example, "He recovered his health" versus "He re-covered the leaky roof" (The Associated Press Stylebook).

As mentioned previously, there is one citation that doesn’t align with the other citations of quoted content: The 4.2. Identifying and Avoiding Slang > Productize entry. If it's decided to keep using footnotes, then this citation would need to be updated for consistency. Or, if we were to update our citation style for direct quotes, it could look something like this:

Original: Not a word. Find another way to say "modify something to become suitable as a commercial product". [wiktionary]

Update: Not a word. Find another way to say "modify something to become suitable as a commercial product" (“Productize”, Wiktionary).

If this is a change worth making, I’d be happy to help update footnotes or other citations into a friendlier format for web-based content.

[julian-cable]

This is a more extensive design change, and I suggest we revisit for a future release after 6.1 is published.

[rclee33]

Agreed, that approach makes sense to me!

[CBID2]

Hi @julian-cable! I would love to make this edit once the update it made.

[julian-cable]

@CBID2 Thanks for your offer of help again! I would be happy for you to work on it after the 6.1 release is completed.

[CBID2]

@CBID2 Thanks for your offer of help again! I would be happy for you to work on it after the 6.1 release is completed.

Absolutely @julian-cable. Just assign the issue me once that happens

[CBID2]

Hey @julian-cable and @rclee33! :) Can I be assigned to this issue? I think the style guide has been updated to 6.1 :)

[rclee33]

Hi, @CBID2! I think we still might be in a change-freeze due to an upcoming migration. (But @julian-cable will correct me if I'm wrong about that!) We'll reach out once we're able to move forward with this. Thanks you!

[CBID2]

Hi, @CBID2! I think we still might be in a change-freeze due to an upcoming migration. (But @julian-cable will correct me if I'm wrong about that!) We'll reach out once we're able to move forward with this. Thanks you!

Thanks @rclee33! :)

[julian-cable]

Hi @CBID2 I really appreciate your enthusiasm in taking on assignments! The publication of the 6.1 release is in progress right now. After that, the style guide will be undergoing a migration: both the published guide and the GitHub repo will be migrated to new sites. We should freeze any further content changes until all parts of the migration are completed, which might take a while. In the meantime, do feel free to consider what further updates would be beneficial. I will inform you when everything is ready to work directly on the content, in its new location. Many thanks!

[CBID2]

Hi @CBID2 I really appreciate your enthusiasm in taking on assignments! The publication of the 6.1 release is in progress right now. After that, the style guide will be undergoing a migration: both the published guide and the GitHub repo will be migrated to new sites. We should freeze any further content changes until all parts of the migration are completed, which might take a while. In the meantime, do feel free to consider what further updates would be beneficial. I will inform you when everything is ready to work directly on the content, in its new location. Many thanks!

Hey @julian-cable! :) Can I start now? I see that 6.1 is published now.

[julian-cable]

@CBID2 I do love your willingness to contribute! However, I'll need to ask you to hold on for a while longer before starting work on any further content changes. We will be migrating the style guide website and this repo, currently pending approvals within Red Hat. It might take a while longer before this is completed, but I'll be sure to let you know when the time comes. Thanks!

[julian-cable]

@CBID2 The project is now ready to start working on content updates for the next release of the style guide, which will be 6.2. If you would like to work on the content for this issue as described here, any contributions would be gratefully received!

[CBID2]

@CBID2 The project is now ready to start working on content updates for the next release of the style guide, which will be 6.2. If you would like to work on the content for this issue as described here, any contributions would be gratefully received!

I'm still interested @julian-cable

[julian-cable]

@CBID2 Great - Feel free to propose any updates to address this issue.

[CBID2]

Hi @julian-cable :) I apologize for my absence. @rclee33, I share your sentiments on using in-line citations and not footnotes. It would increase readability for users as they would not have to scroll all the way to the end to get links to resources.