Re: an architectural diagram

Hi Ruben,

Happy new year to you and the rest of the list! I hope you all had a
great Christmas and that 2017 will be a good year for us all.

2016-12-30 20:08 GMT+01:00 Ruben Verborgh <Ruben.Verborgh@ugent.be>:

> I have tried to create a high-level diagram
> of the topics we aim to tackle and how they relate.
> You can find the source code and resulting diagram here:
> https://github.com/RubenVerborgh/Hydra-Architecture-Diagram/

Thanks for creating the diagram. I think it looks like a great first
step, but it's currently too sparse for me to provide any more
feedback. There's nothing I can disagree with in the diagram. Yet, at
least. ;-)

> This is a work in progress and still requires your input,
> in the form of replies, issues, pull requests, etc.

How do you feel about using PlantUML[1] as the language to describe
this and eventually all diagrams in Hydra? I'm mostly thinking about
it from a source code versioning perspective; we will need to render
the diagrams in SVG or PNG still, but I just find plain text to be a
lot simpler as a versionable piece of information than binary images.

> I have split the diagram in two large packages.
> The first one concerns the modeling of an API's structure
> (which an API would typically send as a separate document).
> The second one concerns the description of hypermedia controls
> (which an API would typically send as part of a representation).

As I think we agreed in our discussion regarding this before
Christmas, this separation makes sense.

> Another purpose of the diagram is to allow us to divide the work:
> there are clear parts that can be considered separately (at first),
> and these could perhaps be part of different draft documents.

Yes, perhaps. While I think it's important that what's common between
API documentation and hypermedia controls should be designed and named
in a common way, I can see how separating these things might improve
our progress and allow us to work more in parallel.

[1] http://plantuml.com/

-- 
Asbjørn Ulsberg           -=|=-        asbjorn@ulsberg.no
«He's a loathsome offensive brute, yet I can't look away»

Received on Tuesday, 3 January 2017 12:09:39 UTC