diff --git a/documentation/style-guide.md b/documentation/style-guide.md new file mode 100644 index 0000000..ee6c670 --- /dev/null +++ b/documentation/style-guide.md @@ -0,0 +1,142 @@ +# Package-URL style guide + +This document provides guidance for writing documentation for Package-URL +projects. It specifically applies to documentation for: +- The PURL specification from `package-url/purl-spec`, +- The VERS specification from `package-url/vers-spec` and +- The Package-URL website from `package-url/packageurl.org`. + +The style guide is also recommended for documentation for any other project +under the `package-url` GitHub organization, but not mandatory. + +## Package-URL terminology +There is some terminology that we need to standardize for documentation, the +website and comments in code. The current list is: + +- PURL: use PURL (all-caps) to refer to the PURL specification or for a +reference to a PURL in technical documentation, not code case. This is a +convention from the ECMA standard. +- VERS: use VERS (all-caps) to refer to the VERS specification or for a +reference to a VERS in technical documentation, not code case. This is a +convention from the ECMA standard. +- Package-URL: Package-URL is tricky because we need to distinguish +between its meaning as a community that is reponsible for the PURL and VERS +specifications and its meaning as the full name for PURL. The primary +guideline is to use Package-URL to refer to the community and PURL to refer +to the specification. +- Specification versus standard: Specification and standard are often used +interchangeably in software and other technical domains and there is no way +to prevent this in our community discussions. For documentation and the +website; + - Use **standard** to refer to the content of the ECMA standards for +PURL (first edition submitted to ECMA for December 2025 approval) or VERS +(first edition to be submitted to ECMA for approval in June or December 2026). + - Use **specification** to refer to the broader set of information about + PURL or VERS, such as the test schemas and test files. Over time, many + elements of the specifications will be added to the standards + +## Other terminology + +### Package names +- Use “npm package”, not “NPM”, because “npm” is the package manager, +not the name of a package. +- Use "Ruby gems" not RubyGems” because RubyGems is the name of a package +distribution service, not the name of a package + +## Active voice + +In general, use active voice (in which the grammatical subject of the sentence +is the person or thing performing the action) instead of passive voice (in +which the grammatical subject of the sentence is the person or thing being +acted upon), although there are exceptions. Make clear who's performing the +action. + +In passive voice, it's easy to neglect to indicate who or what is performing a particular action. In this kind of construction, it's often hard for readers +to figure out who's supposed to do something (such as the reader, the +computer, the server, an end user, or a visitor to a web page). + +## Capitalization + +- Don't use unnecessary capitalization; before you capitalize a word, think +about why (and whether) it should be capitalized. +- Don't rely on a difference in capitalization to convey meaning. For example, + although people who are familiar with Kubernetes probably understand that a + capitalized Pod is a Kubernetes unit, and a lowercase pod is any other kind + of pod, that distinction is likely lost on many casual readers or those who + are new to the domain. +- Don't use all-uppercase, except in the following contexts: in official +names , in abbreviations that are always written in all-caps, or when +referring to code that uses all-caps. +- Don't use camel case, except in official names or when referring to code +that uses camel case. + +## Use sentence case in headings and tables + +In document titles and headings, use sentence case. That is, capitalize only +the first word in the title, the first word in a subheading after a colon, or +any proper nouns or other terms that are always capitalized a certain way. +- Don't put a period at the end of a title or heading. +- Use sentence case for all the elements in a table: contents, headings, +labels, and captions. + +## Diction + +### General +- When possible, avoid using -ing verb forms as the first word in any heading +or title. An -ing verb form is a present participle or gerund. These verb +forms are inconsistently translated when they're used as the first word in a +title, and they increase character count in limited spaces. +- Avoid unnecessary adjectives or adverbs +- Articles: + - Use “a” or “an” with a singular-count noun when you mean “one of many,” + “any,” or “in general.” Example: I like a good movie (one of many movies). + - Use “the” with any noun when the meaning is specific; for example, when + the noun names the only one (or one) of a kind. Example: New York is the + largest city in the United States (only one city can be “the largest”). + - Don’t use “a,” “an,” or “the” with a noun when you mean “any,” “in + general.” Example: He gave me information (not specific). + +### Standard / specification text +- Use GB English for any text that is part of the Ecma standard documentation +for PURL or VERS. +- Use Oxford commas. +- Spelling: + - Use artefact instead of artifact. + - Use behaviour instead of behavior. + - Refer to "#" as hash sign, not number sign. + - Use full stop instead of period. + - Use license as a verb and licence as a noun. +- For standards-related text. + - Use shall instead of must. + - Use may instead of can. +- List items + - Do not use initial caps or punctuation for a list item unless it is a + sentence. + +## Markdown text +- Use the GitHub dialect - see https://docs.github.com/en/get-started/writing-on-github and https://github.github.com/gfm/ for reference. +- Limit lines in a markdown file to 78 character lines to facilitate more +accurate change tracking. + +### Code style +- When to use code style (or not) + +## URL references +- How to refer to URLs - many options + +## Ecma / ECMA + +### Terminology +- ECMA is an acronym for the European Computer Manufacturers Association. +ECMA was renamed to Ecma International in 1994. +- Ecma is an abbreviation for Ecma International. +- Use Ecma International when referring to the organization specifically. +- Use Ecma for most references, such as "Ecma standard" or "Ecma Technical +Committee". +- Use ECMA only for referring to a standards document such as ECMA-424 for +CycloneDX. + +### Ecma document formatting +The text of a document may be sub-divided in clauses, which may again be sub-divided. It is recommended that the number of levels does not exceed 3, +even if the text processing templates developed in Ecma allow for a maximum +of 5 levels. \ No newline at end of file