Minor editorial fixes to architecture diagrams + source files

[shigeya]

Resolves Issue #618.

• DID dereferencer -> DID URL dereferencer
• DID Document -> DID document

Also:

• a minor placement adjustment.
• removing png files

[shigeya]

Since the files that need to change are the same, please let me continue with this branch.

Files are converted to diagrams.net (previously known as draw.io) format. It can be editable either at diagrams.net or a downloadable application. Software is freely available.

Files are placed into the diagrams directory. We may want to relocate diagrams/src or such directory.

Also, during the conversion process I did:

• Font changed to Helvetica instead of Helvetica Neue
• Placement adjustment, minor edits in .drawio files (not painful but require 1hr adjustment work)
  • Also tweaked arrowheads and line width.
• Placed newly exported .svg files -- verified with Safari, Chrome, Firefox, and Brave.

For review, attached please find the newly generated PNGs (PNGs are not added to repository)

[shigeya]

some tips on diagrams.net and export to SVG:

• diagrams.net drawio format can embed editable objects into SVG or even to PNG. You can select whether embed the editable objects or not in the export dialog. If you select to embed, the resulting file is large ( nearly 4MB ), but SVG only export is only 20-60KB. Don't forget to turn off the embed option when you export.
• When export, don't forget to add some extra border in the same export dialog box (Border Width option). Default is zero. I set it to 10.
• I used Visio format as an intermediate format. The desktop version of the diagrams.net app is old, and it can't import Visio file. Use Web site version to convert.

[shigeya]

Minor fixes to diagrams pushed. Matches arrow origin as previously merged graphics, text placement adjustments.

[msporny]

@shigeya, this is ready to merge, but I keep halting the merge because it seems like you're still working on this PR. Please let me know when you are ready to merge it into the repository.

[shigeya]

@msporny I think it's almost good to go. Let me review them one more time tomorrow afternoon (JST - it's almost 18 th) and let you know.

Also, do you have any good suggestions on where to store the above tips somewhere in the document? Or we don't need it once merged? Storing in README.md in the diagrams directory is one of the solutions. Possibly in top-level README.md or CONTRIBUTINGS.md files.

[msporny]

Also, do you have any good suggestions on where to store the above tips somewhere in the document? Or we don't need it once merged? Storing in README.md in the diagrams directory is one of the solutions. Possibly in top-level README.md or CONTRIBUTINGS.md files.

Please put it in the README.md to reduce the chance that contributors will miss it.

[shigeya]

@msporny I made a few minor adjustments. Now, they're ready to go. Notes on diagrams.net added to README also. Rebased and squashed changes too.

Note: On file size, I was partially wrong. I accidentally left working canvases in .drawio files, so I removed them. Now, the .drawio file is much smaller than the SVG files. But still, the SVG file is smaller than embedded (SVG+drawio objects) so, the workflow kept the same.

[rhiaro]

I find the DID Document --refers to--> External resource a bit odd. It might be confusing for someone new at least, so perhaps it is not necessary on the simple overview diagram? (I'm assuming 'external resource' means a service? as key material should be internal to the DID doc. In which case it should just say 'service' and not be general, unless I'm missing something.)

However, if we keep DID Document --refers to--> External resource, External resource could be moved to the middle row on the left side, between DID Subject and DID Controller to reduce arrows which cross over each other.

I think DID --identifies--> DID Subject should be DID --refers to--> DID Subject

I'm not sure DID URL --fragment refers, and dereferences, to--> DID document is quite right - is the word 'fragment' out of place here?

(When I look at the SVG locally lots of the text overlaps the lines, but maybe that's just for me.. might be a local fonts issue.)

[shigeya]

@rhiaro I want to know this one first.

(When I look at the SVG locally lots of the text overlaps the lines, but maybe that's just for me.. might be a local fonts issue.)

Please kindly let me know which browser you're using (version, also platform). If possible, please take a screen snapshot and post it here.

[rhiaro]

@shigeya not in browser, in my local native image viewer (Eye of MATE) on linux

[shigeya]

@rhiaro

not in browser, in my local native image viewer (Eye of MATE) on linux

Thank you very much. I've checked the diagrams rendered correctly on latest production version of Safari, Chrome, Firefox, Edge and Brave on Mac. I believe it is already good enough, but maybe worthwhile to check it on Windows and Linux for sure. If you find this kind of issues on browsers, please let me know.

In the past version of my diagrams, there was compatibility issue on (at least) Chrome and Firefox. It was due to the font which I accidentally used. I think it's compatible among wider range of browsers now.

I will follow other topics you mentioned soon.

[shigeya]

@rhiaro

I find the DID Document --refers to--> External resource a bit odd. It might be confusing for someone new at least, so perhaps it is not necessary on the simple overview diagram? (I'm assuming 'external resource' means a service? as key material should be internal to the DID doc. In which case it should just say 'service' and not be general, unless I'm missing something.)

Very good point. If we remove it, we can reduce complexties a lot. Also external resources are not mentioned in the section. But now, adding a figure in dereference section become mandatory, I think.

However, if we keep DID Document --refers to--> External resource, External resource could be moved to the middle row on the left side, between DID Subject and DID Controller to reduce arrows which cross over each other.

I know. But people tend to see the figure from top-left towards bottom-right. I prefer external items to the right.

So, removing External Resource from this figure is the way to go.

I think DID --identifies--> DID Subject should be DID --refers to--> DID Subject

It's from original diagram's text. And I prefer your suggestion a lot.

I'm not sure DID URL --fragment refers, and dereferences, to--> DID document is quite right - is the word 'fragment' out of place here?

You're right. It is still correct even if we eliminate 'fragment'; the removal also reduce complexities. It's an artifact from detailed version, and it is correct in certain context, but not necessary in this level of brief description.

Below is the version reflect the suggestions. Thanks!

[iherman]

@shigeya not in browser, in my local native image viewer (Eye of MATE) on linux

@rhiaro I think that is the typical font issue. I presume the draw.io generation keeps the characters as opposed to turn the characters into pure geometry. This is the proper way to do it in terms of, say, accessibility, but that may then lead to problems with fonts.

I do not run Linux and, I presume, Shigeya also runs a mac. Could you check this in browsers on Linux? They may take care of fonts (in case the fonts are not available locally), in which case we may be fine.

[iherman]

I do not want to hold this up for longer... but I am still a little bit uncomfortable with the way fragments are referring to. I repeat what, I believe, already said: a DID URL of the form did:ex:12343/path/#fragment, for example, does not necessarily follow the relationship labeled as "fragment refers, and dereferences, to" arrow but, rather, the "dereferences to" one. The only time a fragment indeed refers to what you describe is when it is of the form did:ex:12334#fragment.

At this moment my mind goes a bit blank on how to represent this, succinctly, on the diagram. It may be as simple as making this point clear in the caption of the figure. And also (or instead?) labelling that arrow with "fragment may refer, and dereference, to".

[shigeya]

I presume the draw.io generation keeps the characters as opposed to turn the characters into pure geometry. This is the proper way to do it in terms of, say, accessibility, but that may then lead to problems with fonts.

Diagrams.net doesn't convert texts to outline. I noticed the previous version of the architecture diagram converts texts to outlines. Is there any preference or guidelines at W3C?

[iherman]

I presume the draw.io generation keeps the characters as opposed to turn the characters into pure geometry. This is the proper way to do it in terms of, say, accessibility, but that may then lead to problems with fonts.

Diagrams.net doesn't convert texts to outline. I noticed the previous version of the architecture diagram converts texts to outlines. Is there any preference or guidelines at W3C?

Keeping the text has lots of advantages: it is searchable, it is more accessible, and the file is smaller. But it incurs the danger of looking bad due to font issue. I think the preference would be to go the way you do it, but it is something we may want to weight against the problem.

What I usually try to do is to dump a good quality PNG file (possibly generated from the SVG), add it to the package, and add a reference to the PNG file from the caption (something like "image also available in PNG format")

[shigeya]

I do not want to hold this up for longer... but I am still a little bit uncomfortable with the way fragments are referring to. I repeat what, I believe, already said: a DID URL of the form did:ex:12343/path/#fragment, for example, does not necessarily follow the relationship labeled as "fragment refers, and dereferences, to" arrow but, rather, the "dereferences to" one. The only time a fragment indeed refers to what you describe is when it is of the form did:ex:12334#fragment.

At this moment my mind goes a bit blank on how to represent this, succinctly, on the diagram. It may be as simple as making this point clear in the caption of the figure. And also (or instead?) labelling that arrow with "fragment may refer, and dereference, to".

I share the same feeling.

At this moment, I think, the brief version of the diagram should only represent the relationship discussed in the overview section it belongs to. I also think it is possible to achieve clarity and simplicity even by removing part of the spec text to simplify the discussion in the section. The section's text and the brief version of the diagram should correctly match.

For the detailed version, it should depict as much detail as it can. It may be impossible to achieve. But I think there is a way; related to PR #648, there are several people showing their views on dereferences. To have an agreeable diagram, I start feeling that we want to collect example DID URL-s which cover most of the cases we can imagine at this moment, then, reflect the possibilities onto the detailed figure. The list of collections of DID URL-s will help understand how dereferencer works.

[msporny]

Yes! to the image below. That's what I was hoping we'd get to. Everything else can be stuffed into a separate section or into an appendix:

I would argue that we simplify further and remove DID URL from the architecture diagram, and move that further down into the DID URL section. Yes, it's an important concept, but we can introduce it later.

[iherman]

Yes! to the image below. That's what I was hoping we'd get to

-1

A DID URL does not necessarily dereference to a DID document and that is what the diagram suggests.

[msporny]

A DID URL does not necessarily dereference to a DID document and that is what the diagram suggests.

Ok! Then let's just remove it from the diagram and put it in the DID URL and/or dereferencing section. At this point, I just want to get to a simple DID Architecture diagram, and all the complexity around DID URLs (which I've never been entirely comfortable with) should move to future sections. It's not necessary to understand DID URLs to get a basic understanding of the ecosystem.

[iherman]

A DID URL does not necessarily dereference to a DID document and that is what the diagram suggests.

Ok! Then let's just remove it from the diagram and put it in the DID URL and/or dereferencing section. At this point, I just want to get to a simple DID Architecture diagram, and all the complexity around DID URLs (which I've never been entirely comfortable with) should move to future sections. It's not necessary to understand DID URLs to get a basic understanding of the ecosystem.

I can live with that.

[TallTed]

A DID URL does not necessarily dereference to a DID document and that is what the diagram suggests.

How about "DID URL refers, and/or dereferences, to DID document" (note the added /or)?

Also -- I see no reason why we shouldn't, and several reasons why we should, include more than two diagrams. Starting from the simplest possible, and adding complexity as it arises in the text. Kind of the way the onionskin or plastic pages in an anatomy book layer skin over blood vessels over muscles over tendons over bones (or whatever the order is; I'm not an anatomist)...

Three might be all we need, or we might need 4 or 5. Probably not more than that.

[shigeya]

We need three types of diagrams:

1. A brief overview diagram in Sec. 1.3 architecture overview which describes the relationship of the components described in the section ( in Manu's word: "Basic Understanding of the Eco System")
2. Multiple dereference relationship diagrams in dereferencing section to understand the possible outcomes of dereferences. Maybe in the dereferencing section (not in DID URL section, IMO. )

3. (Optional) A detailed overview diagram showing the entire DID architecture (We may need adjustments)

   1. A brief overview

I think the section's text should be in sync with the diagram. If the diagram needs to be simple, the text also should.

@TallTed said:

How about "DID URL refers, and/or dereferences, to DID document" (note the added /or)?

I think it's too complex to decipher for this diagram. Also, I found the text in Sec 1.3, which is not in sync with the above proposal:

DID URL dereferencers and DID URL dereferencing A DID URL dereferencer is a system component that takes a DID URL as input and produces a serialized resource as output.

If we concern about the text attached to the arrow, we should revise it.

And now I realize the diagram is not showing dereferncer (which I removed). Do we need to mention function in this diagram? or the text in the section needs to mention this complex function?

2. Dereference relationship diagrams

I feel the difficulty of discussing dereference comes from the lack of shared ideas of possible resolution patterns.

Three might be all we need, or we might need 4 or 5. Probably not more than that.

I guess four or five, but first, we need to agree on which pattern should be included.

I wrote (rephrased)

To have an agreeable diagram, I start feeling that we want to collect example DID URL-s that cover most of the cases we can imagine and then reflect the possibilities onto the detailed figure.

I want the WG to have a shared idea of the DID resolution pattern that needs to be described, possibly with a diagram.

I believe this helps developers understand how the WG members want dereferncer to be without losing extensibility.

3. (Optional) A detailed overview diagram

The current diagram in Appendix needs an update. Whether it is reasonably possible or not depends on the above discussion on dereferencing. If the diagram can't show enough detail, dropping the diagram is an option, so I marked this as optional.

[msporny]

@shigeya -- we need to merge this PR... we're running out of time. We're done w/ the other pre-CR PRs and are finalizing the specification now. Please commit what you have now, clean up the merge conflicts. The Editors have a clear idea of what to do with the diagrams (building off of the very important work you've done) and can take the diagrams from here.

[shigeya]

@msporny

@shigeya -- we need to merge this PR... we're running out of time. We're done w/ the other pre-CR PRs and are finalizing the specification now. Please commit what you have now, clean up the merge conflicts. The Editors have a clear idea of what to do with the diagrams (building off of the very important work you've done) and can take the diagrams from here.

Sure. Resolved the conflict in ECHIDNA file (eliminated the commit which includes edit for ECHIDNA file) and pushed.

The commits in this PR contain the latest I have. There are some experimental works for dereferencing section in #648 but can be dropped, of course.

[msporny]

@shigeya wrote:

Sure. Resolved the conflict in ECHIDNA file (eliminated the commit which includes edit for ECHIDNA file) and pushed.

Thank you @shigeya !

[msporny]

Editorial, multiple reviews, changes requested and made, no objections, merging.