Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FAQ appendix cleanup #733

Merged
merged 5 commits into from
May 14, 2021
Merged

FAQ appendix cleanup #733

merged 5 commits into from
May 14, 2021

Conversation

rhiaro
Copy link
Member

@rhiaro rhiaro commented May 9, 2021

For #728

Removed FAQ style headings and responses, trimmed down some text, made some language consistent.

Note - one subsection said DID docs can be used to serve representations of resources, like schemas. I thought the group had resolved that DID docs should have minimal stuff for the specific needs of DIDs, and that any more than this was bad practice (per the resource=true discussion) so I've updated it to say to use a DID parameter to do this but didn't mention the resource parameter as it still doesn't have a spec linked in the Registries. This is a separate commit though so can revert if I got the wrong end of the stick.

Also added a paragraph aiming to address #718 about whether the DID subject can change.


Preview | Diff

rhiaro added 4 commits May 9, 2021 21:49
Trim down wording, remove FAQ style headers, make use of 'refers to'
instead of 'identifies' consistent.
@iherman
Copy link
Member

iherman commented May 10, 2021

Thanks @rhiaro,

  • I do not think the (new) title "Implementation Guidance" is an appropriate replacement for FAQ. Many (most?) of the sections are related to the way DID are to be used rather than implemented, and they also often clarify conceptual details. I am not sure what to offer instead, though. "Usage Notes", "Usage Guidance"...: neither of these sound exactly right, but I am sure you can come up with something better.
  • Several sections make use of the alsoKnownAs property but the property itself is still marked as at risk. I seem to remember that, after all, alsoKnownAs will stay as a bona-fide property, but I did not see any PR or issue on this. It would be good to sync this...
  • This is a more general editorial issue, in fact. I think it is good practice to mark all appendices (maybe except for the IANA one) as non-normative.
    Another approach would be to put a generic statement into the conformance section. But I personally think marking each appendix as non-normative is better.

@rhiaro
Copy link
Member Author

rhiaro commented May 10, 2021

Thanks @iherman. I meant to note about the main heading - I definitely wasn't sure about Implementation Guidance, and was looking for feedback on that.

I thought appendices were non-normative by definition, but I can add that explicitly if necessary.

If alsoKnownAs gets dropped during CR we can certainly remove mentions of it from the appendices.

index.html Outdated
@@ -5987,99 +5990,78 @@ <h2>application/did+cbor</h2>
</section>

<section class="appendix">
<h1>Frequently Asked Questions about DID Identification</h1>
<h1>Implementation Guidance</h1>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps this could be

Suggested change
<h1>Implementation Guidance</h1>
<h1>Appendix</h1>

Copy link
Member

@msporny msporny May 14, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have multiple appendices... If we took this change, the spec would read: "Appendix C: Appendix"... which might not be the most helpful title. :P

index.html Outdated Show resolved Hide resolved
@msporny
Copy link
Member

msporny commented May 14, 2021

Editorial, multiple positive reviews, no objections, merging.

@msporny msporny merged commit 79893da into main May 14, 2021
@msporny msporny added cr-comment editorial Editors should update the spec then close labels May 22, 2021
@msporny msporny deleted the rhiaro-728-appendix branch May 30, 2021 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
editorial Editors should update the spec then close
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants