Documentation

[jchatfranklin]

Identity repo introduction needs editorial review, copy edit

[jchatfranklin]

Made edits in the body. Have multiple questions for reviewer(s), a few of which are because I'm unfamiliar with all of the terminology and style practices. (Is there an editorial style guide, which would include how we refer to various technologies, vendors, and features?) Uncertain how to leave comments in the file, so I'm including them here; please advise how better to do this going forward:

GENERAL NOTES
Flesh out sub-heds -- for example, instead of "Core Commands to Use the CLI," suggest "Core Commands for Using the AGNTCY Agent Directory CLI." Longer, for sure, and more ponderous, mostly, but much, much better for SEO and, presumably, for AI crawlers, as well.

We use an awful lot of acronyms. Is there any way to reduce these? Regardless, need a consistent style, e.g., full term spelled out followed by the corresponding acronym in parentheses. It's inconsistent. Also, standard MFA and AP style historically has been to use the full-term followed by the acronym the first time only, and then just use the acronym. Is this possible?

Sub-heds are inconsistent as to case -- Headline or all-initial capped? Suggest Headline for for H1 and perhaps H2, and first-word initial cap only for H3 and H4 (if we have an H4).

Specific Questions:

2nd bullet below diagram:
Diff "Agent Badges" and "Agent Cards?"
"...can provide nuanced, task-specific assess to different systems..." -- meaning tasks such as...?

bulleted list below "Verifiable Credentials"
there are 3 bullets in this list. But there are 7 items in the VC balloon of the diagram. Standardize?

Note
"...all identity-bearing entities in the IoA" suggest spelling out "IoA" (presumably "Internet of Agents.")

Architecting Agentic Trust, 1st bulleted list
Shouldn't we capitalize the "D" in "IDPs?"
Not sure we need to include the "MASs" acronym. If we do, need to be consistent, and place the acronym after the full term (in sub-bullet 3, the acronym precedes the spelled-out term).
Do we refer to "AGNTCY" or "the AGNTCY?"
last sentence -- suggest replacing "!" with "."

Features & Main Components" -- features and main components of what? The identity feature?
Is it "Backend" or "Back end?"

Get Started in 5 Minutes
Sentence 3 -- is it "...both on local storage AND using a 3rd-party..." or is it "...EITHER on local storage or using a 3rd-party..."?

Step 3 -- Verify the Installation
Different commands available for... what?

Run the Demo / Prerequisites
First sentence instructs to follow the steps in the "Getting Started" section above to "...generate a local vault and keys." But unless I missed it, that section does not include such a step.

Step 2 -- Use the CLI to create a local Vault and generate keys -- inconsistent terminology; under "Prerequisites" it says "...generate a local vault and keys." Also, is it an upper-case or lower-case "V?" I'm probably splitting hairs, here, but do you create one and generate the other, or do you create both or generate both? Just thinking if we're ruthlessly consistent we'll make it just a bit easier for people coming on-board to enter their agents.

Step 3 -- Register as an Issuer
I'm a bit confused, I'm afraid, as to where the prerequisites leave off and where the procedural steps begin. For example, the first sentence under the Prerequisites" sub-hed mentions generating a local vault and keys. But Step 2 shows how to create a local vault and generate keys.

Step 5 -- Issue and Publish a Badge for the MCP Server
Is it "VCS," "VCs," or "vcs?" Suggest avoiding the latter 2 (and perhaps all 3), as most people, I think, will in their minds think of venture capitalists.

[beryder]

Thank you for raising the issue and creating PR #138, I suggest that you copy each of your general notes and specific questions as separate comments in PR #138 - and then we can start threads to discuss and resolve each one as needed