Conversation
Added missing links and slight punctuation changes in bullet list.
| * How a [BTCR2 Beacon] can be established and added as a service to a DID document; | ||
| * How [BTCR2 Update Announcements][BTCR2 Update Announcement] are broadcast within [Beacon Signals][Beacon Signal]; and |
There was a problem hiding this comment.
I believe this was originally correct (as much as I understand Simplified Technical English). See Section 4.3 "Vertical Lists" in https://robertobertuol.com/wp-content/uploads/2018/08/ASD-STE100-ISSUE-7.pdf
I'll reproduce it here as best I can:
Rule 4.3 Use a vertical list for complex text.
When you must include many different items or actions in a sentence, you can put them in a vertical list. Vertical lists make long complex sentences much easier to read and understand.
When you make a vertical list:
-
Put a colon (:) at the end of the main part of the sentence, before the first item in the vertical list.
-
Identify each item in the vertical list with a number, letter, punctuation mark or symbol. For example, you can use:
- A dash (-)
- A letter (b)
- A number (7)
- A bullet point (•)
To know which marks or symbols to use, refer to the applicable specifications for technical publications, style guides, and other official directives.
-
Start each item in the vertical list with an uppercase letter.
-
Put a full stop (period) at the end of an item in the vertical list if it is a full sentence.
-
Do not put a full stop or a comma at the end of an item in the vertical list if it is not a full sentence.
-
Put a full stop at the end of the last item in the vertical list.
Rule 8.1 says to avoid semicolons.
Rule 8.1 You can use all standard English punctuation marks except the semicolon (;).
Why Simplified Technical English? Another option is "Plain Language" but I don't know how well the writing rules are codified. At least with STE, I can point to a specific rule for justification.
There was a problem hiding this comment.
This is extremely helpful, thank you! We use a different bullet style for other writing projects (semicolons at the end of each bullet, except for the last one), which is what led to the question. If STE is the standard for this spec, I'll just make sure the rest of the lists conform as described above.
There was a problem hiding this comment.
FWIW, nobody officially adopted or agreed on STE or Plain Language for the spec. These are just the style guides I found for copyediting technical writing.
Claude Code and Codex can apply style transfer with STE or Plain Language. Here are some previous PRs I created with Codex, for example:
There was a problem hiding this comment.
Thank you for the Codex examples. I've found a few sections of text that contain complex lists that really should be separated by semicolons (if we want to preserve these as full sentences), or potentially converted into a bulleted list if we aren't using semicolons. I'll take a closer look to see if any can just be separated into shorter sentences, and open an Issue if needed to discuss the best way to manage these.
| A [CAS Beacon] creates a [Beacon Signal] that commits to multiple [BTCR2 Update Announcements][BTCR2 Update Announcement] through a [Beacon Announcement Map]. To do so, it constructs a Map where the key is the **did:btcr2** identifier and the value is the hash of the corresponding [BTCR2 Update]. The [Beacon Signal] contains a SHA-256 hash of the Map. | ||
|
|
||
| If a [BTCR2 Update] is not publicly discoverable (i.e., is not published to a CAS under its hash), the only parties with access to the update are the DID controller and any parties they gave it to (etc.). | ||
| If a [BTCR2 Update] is not publicly discoverable (i.e., is not published to a [CA]S under its hash), the only parties with access to the update are the DID controller and any parties they gave it to (etc.). |
There was a problem hiding this comment.
The link doesn't work.
| If a [BTCR2 Update] is not publicly discoverable (i.e., is not published to a [CA]S under its hash), the only parties with access to the update are the DID controller and any parties they gave it to (etc.). | |
| If a [BTCR2 Update] is not publicly discoverable (i.e., is not published to a [CAS] under its hash), the only parties with access to the update are the DID controller and any parties they gave it to (etc.). |
Also, the "(etc.)" here is really annoying just prior to the full stop.
I would probably remove it entirely, but another alternative might be removing the parentheses and additional period:
... they give to it, etc.
There was a problem hiding this comment.
I have a note to create an Issue on the (etc.). to ask why it is there and to see if it can either be removed or rewritten. I'm definitely in favor of it not appearing as it does currently.
4 participants
Added missing links and slight punctuation changes in bullet list.