opendatahub-io/docs-skills/ibm-sg-references

IBM Style Guide: References review skill

Review documentation for reference issues: citations, footnotes, geographic locations, names, product and service names, trademarks, and product versions.

Precedence: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules where guidance conflicts.

Checklist

Citations and references

• [ ] Sources are cited for all statistics, quotes, and external claims
• [ ] Citation format is consistent throughout the document
• [ ] Full URLs are provided for online references (no shortened URLs)
• [ ] Access dates are included for web citations that may change
• [ ] Links point to the most specific page, not the homepage

Footnotes

• [ ] Footnotes are used sparingly; inline explanations or links are preferred
• [ ] Essential information is not placed in footnotes
• [ ] Footnotes are numbered sequentially
• [ ] Procedures and code examples are not in footnotes

Geographic locations

• [ ] "Domestic" and "foreign" are not used; specific countries or regions are named
• [ ] Official, current names are used for countries and regions
• [ ] Reader's location is not assumed ("here," "local," "our country")
• [ ] Countries and regions are listed alphabetically unless logically ordered

Names and titles

• [ ] Full official names are used on first reference; shortened forms afterward
• [ ] Courtesy titles (Mr., Ms., Dr.) are avoided unless relevant
• [ ] Preferred spelling and capitalization of names are followed

Product and service names

• [ ] Full official product name is used on first reference in each topic
• [ ] Product names are not abbreviated without an official abbreviation
• [ ] Product names are not used as verbs: "search by using Google" not "Google it"
• [ ] Product names are not used as generic terms: "container" not "Docker" (when generic)
• [ ] Trademark symbols (™, ®) appear only on the first prominent use, not every instance
• [ ] Vendor's exact capitalization is followed: "macOS," "iOS," "GitHub," "PostgreSQL"

Product versions

• [ ] Full version format is used: "Version 4.12" or "v4.12"
• [ ] Versions are specific: "version 4.12 and later" not "recent versions"
• [ ] "Current version" and "latest version" are not used (they become outdated)
• [ ] Minimum required versions are specified: "requires version 2.1 or later"
• [ ] Version formatting is consistent throughout

How to use

1. Review only changed content and necessary context
2. For each issue found, cite the relevant IBM Style Guide section
3. Mark issues as required (incorrect product names, missing citations) or [SUGGESTION] (formatting preferences)

Example invocations

• "Review this file for reference and naming issues"
• "Check product names and versions in the release notes"
• "Do an IBM references review on modules/overview.adoc"

References

For detailed guidance, consult:

• IBM Style Guide: References sections