From 7719ca5575d0162ad429f2901cf0e86f003769f4 Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Thu, 30 Oct 2025 17:58:14 -0700 Subject: [PATCH 1/7] Create style guide First draft of a documentation style guide for Package-URL projects. --- documentation/style-guide.md | 74 ++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 documentation/style-guide.md diff --git a/documentation/style-guide.md b/documentation/style-guide.md new file mode 100644 index 0000000..a6029c8 --- /dev/null +++ b/documentation/style-guide.md @@ -0,0 +1,74 @@ +# 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 `packag-url/packageurl.org`. + +It is also recommended for documentation for any other project under the +`package-url` GitHub organization. + + +## Package-URL Terminology +- PURL +- VERS +- Package-URL + +## 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, lists 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. +- Even though you're using sentence case, don't put a period at the end of a +title or heading. +- Use sentence case for items in a list. +- Use sentence case for all the elements in a table: contents, headings, +labels, and captions. + +## Diction + +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 adjective or adverbs +- A vs the vs nothing +- GB English for Ecma standard documents + + +## Line length +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 \ No newline at end of file From 142186074c3698d03a5ebb534a4a309ff274574b Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Fri, 31 Oct 2025 10:35:46 -0700 Subject: [PATCH 2/7] Update style-guide.md --- documentation/style-guide.md | 71 ++++++++++++++++++++++++++++++------ 1 file changed, 59 insertions(+), 12 deletions(-) diff --git a/documentation/style-guide.md b/documentation/style-guide.md index a6029c8..072f495 100644 --- a/documentation/style-guide.md +++ b/documentation/style-guide.md @@ -6,16 +6,37 @@ projects. It specifically applies to documentation for: - The VERS specification from `package-url/vers-spec` and - The Package-URL website from `packag-url/packageurl.org`. -It is also recommended for documentation for any other project under the -`package-url` GitHub organization. - +The style guide is also recommended for documentation for any other project +under the `package-url` GitHub organization, but not mandatory. ## Package-URL Terminology -- PURL -- VERS -- Package-URL +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 ## 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 @@ -27,6 +48,7 @@ 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, @@ -41,14 +63,14 @@ referring to code that uses all-caps. that uses camel case. ## Use sentence case in headings, lists 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. -- Even though you're using sentence case, don't put a period at the end of a -title or heading. +- Don't put a period at the end of a title or heading. - Use sentence case for items in a list. - Use sentence case for all the elements in a table: contents, headings, -labels, and captions. +labels, and captions. ## Diction @@ -61,14 +83,39 @@ and they increase character count in limited spaces. - GB English for Ecma standard documents -## Line length +### Line length Limit lines in a markdown file to 78 character lines to facilitate more accurate change tracking -## Code style +### Code style - When to use code style (or not) ## URL references -- How to refer to URLs - many options \ No newline at end of file +- How to refer to URLs - many options + + +## Ecma / ECMA +from the Ecma directives +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. + +### 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 standard document such as ECMA-424 for +CycloneDX. + +### GB English +The following conventions apply to any text that is part of the Ecma standard +for PURL or VERS. +- Use Oxford commas, +- Spelling: + - behaviour + - \ No newline at end of file From aaa68ef9ece4be17cb69dca400b5092eb6bb5059 Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Sun, 2 Nov 2025 15:51:30 -0800 Subject: [PATCH 3/7] Update style-guide.md --- documentation/style-guide.md | 47 ++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/documentation/style-guide.md b/documentation/style-guide.md index 072f495..03aef0d 100644 --- a/documentation/style-guide.md +++ b/documentation/style-guide.md @@ -4,7 +4,7 @@ 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 `packag-url/packageurl.org`. +- 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. @@ -74,33 +74,35 @@ labels, and captions. ## Diction -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 adjective or adverbs -- A vs the vs nothing -- GB English for Ecma standard documents - +- 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). +- 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 ### Line length 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 -from the Ecma directives -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. ### Terminology - ECMA is an acronym for the European Computer Manufacturers Association. @@ -109,13 +111,10 @@ ECMA was renamed to Ecma International in 1994. - 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 standard document such as ECMA-424 for +- Use ECMA only for referring to a standards document such as ECMA-424 for CycloneDX. -### GB English -The following conventions apply to any text that is part of the Ecma standard -for PURL or VERS. -- Use Oxford commas, -- Spelling: - - behaviour - - \ No newline at end of file +### 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 From 5cba859c14ac852c34d87f462a2c1d588550e95f Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Fri, 7 Nov 2025 15:10:03 -0800 Subject: [PATCH 4/7] Update style-guide.md --- documentation/style-guide.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/documentation/style-guide.md b/documentation/style-guide.md index 03aef0d..6ccc0b7 100644 --- a/documentation/style-guide.md +++ b/documentation/style-guide.md @@ -9,7 +9,7 @@ projects. It specifically applies to documentation for: The style guide is also recommended for documentation for any other project under the `package-url` GitHub organization, but not mandatory. -## Package-URL Terminology +## Package-URL terminology There is some terminology that we need to standardize for documentation, the website and comments in code. The current list is: @@ -35,6 +35,14 @@ PURL (first edition submitted to ECMA for December 2025 approval) or VERS 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 since “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 From ddb0fb42c06a4dff0cb2bbed7dd679871be4b819 Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Fri, 7 Nov 2025 15:12:48 -0800 Subject: [PATCH 5/7] Update style-guide.md --- documentation/style-guide.md | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/documentation/style-guide.md b/documentation/style-guide.md index 6ccc0b7..4f0ba85 100644 --- a/documentation/style-guide.md +++ b/documentation/style-guide.md @@ -82,27 +82,41 @@ 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. +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 “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”). + 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, +- Use Oxford commas. - Spelling: - - Use artefact instead of artifact - - Use behaviour instead of behavior - - Refer to "#" as hash sign, not number sign - -### Line length -Limit lines in a markdown file to 78 character lines to facilitate more -accurate change tracking + - 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 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) From eefc0fc6b633de0339cb88cd2e8ad49a6570b9bf Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Sat, 8 Nov 2025 15:10:05 -0800 Subject: [PATCH 6/7] Update style-guide.md --- documentation/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.md b/documentation/style-guide.md index 4f0ba85..7ec3f57 100644 --- a/documentation/style-guide.md +++ b/documentation/style-guide.md @@ -38,7 +38,7 @@ PURL (first edition submitted to ECMA for December 2025 approval) or VERS ## Other terminology ### Package names -- Use “npm package”, not “NPM”, because since “npm” is the package manager, +- 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 From 0b4bf6cc9d114b03f2437df25d3e548266dc78e5 Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Mon, 10 Nov 2025 14:50:03 -0800 Subject: [PATCH 7/7] Update style-guide.md --- documentation/style-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/style-guide.md b/documentation/style-guide.md index 7ec3f57..ee6c670 100644 --- a/documentation/style-guide.md +++ b/documentation/style-guide.md @@ -70,13 +70,12 @@ 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, lists and tables +## 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 items in a list. - Use sentence case for all the elements in a table: contents, headings, labels, and captions. @@ -111,7 +110,8 @@ for PURL or VERS. - Use shall instead of must. - Use may instead of can. - List items - - Do not use punctuation for a list item unless it is a sentence. + - 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.