Re: moving forward—with a plan

Hi Ruben

This a very important email. It is evident that the group has lost
momentum, yet we are far from the goal still.

TL;DR;

We must encourage more active participation in crafting the 
specification and features. Lengthy email discussions don't cut it.

Long reply:

In my opinion there are three main factors which hinder our progress.

1. I think that there is a great deficiency abound tooling used to
maintain and contribute to the community.

I. Call me hip but I find mailing lists old-fashioned. There is a
repeating problem with HTML vs. plain text and JSON samples keep
breaking for me. Long threads are a pain, especially when they branch to
weakly related subjects. I also don't agree that it's easy to search,
not to mention the horrible online viewer. And instead of actually
contributing real changes, which would push the specs forward, we end up
with endless, hard to follow discussions.

II. W3C wiki is usually a dead end, which never gets updated and is hard
to navigate.

III. Finally, there is GitHub which we don't use enough. The issues
there are mostly outdated and disconnected from the discussions unless
Ruben or Markus remember to add a link.

2. Second issue is simple IMO. We need to address real issues and offer
concrete, working solutions. Currently the spec is hard to process and
lacks complete examples. Not to mention tooling, but that will likely
come when people start to understand and appreciate the benefits of what
Hydra tries to accomplish.

3. And so, Hydra needs a clear vision of what it actually does. Markus' 
console is a great showcase but it went out of sync with the specs 
lately. And without detailed examples it's not so easy to understand why 
and how it works...

----

Like it or not, Hydra must compete with other modern hypermedia
solutions, eg. Open API Initiative. Just have a look at their GitHub
page [1]: 299 closed issues, 164 closed pull requests, 3600 stars.
GitHub has many advantages over the current flow. It integrates issues,
proposed changes and specification/examples' source code.

I think we should take advantage of GitHub's features as one way to
attract more contributors:

* Move long running discussions to GH issues (better search, actual code
snippets, easy links between issues and code)
* Use code comments to discuss the spec and pull requests
* Maybe move the specification from HTML to markdown and publish with
GutHub pages (anyone else noticed that the published specification URL
is down sometimes?)
* Possibly use raw GitHub URLs + repo tags to track and test-drive past
and future versions of Hydra.
* Most people host code on Hydra and so integration between Hydra Core 
repository and implementations' repositories will also be a plus

I would think that with everything (issues/discussions, spec and pull
requests, wiki and examples) concentrated on GitHub it will be way
easier for people to discover Hydra, find answers and contribute.

>
> Our use cases are starting to move at a higher speed now, with
> different people actively developing different variations of the
> interface. Such variations only make sense if we can describe to
> clients what is going on. Unfortunately, the Hydra Core Vocabulary
> currently cannot keep up. We could interpret this in two ways:
> either we are moving too fast, or Hydra is moving too slow. Of
> course, all of us here have done our best to keep things moving. A
> particular attempt at this is the very long thread about filters. Yet
> after months of work, and the feeling we are almost there, nothing
> has materialized.

There is a long way from the mailing list, to agreement, to actually 
writing the spec down.

Also, maybe it is the right moment to consider introducing some kind of
extensibility to Hydra so that you can develop custom features you need 
and then discuss/contribute them back to Core vocabulary?

>
> We could see this as a sign we need to resurrect that thread, but I
> doubt this is what's really needed. What I think we need is a
> different way of managing the Hydra effort altogether. Perhaps we
> need weekly, bi-weekly, or monthly calls. Perhaps we need a steering
> committee or dedicated task force.

I would not like to see Hydra go the way you propose. I fear the such
cyclical meetings and some kind of task force would actually drive
people away. This completely loses the openness and gives the impression
that there is some closed group of dissidents pulling the strings. What
we need is an open community which will contribute ideas and their
needs.

However, a few calls could be good to discuss how we want to execute the 
required changes to actually start moving forward again. From then on I 
would expect calls to be a rare occurrence.

> But I need to see Hydra move at a sustainable pace, with clear
> milestones, deliverables, and commitment. Otherwise, we'll have no
> choice but to pursue other paths—and that would be a shame. I'm more
> than willing to invest time in Hydra, but then I need to be able to
> see where we are going, and when.

What if Hydra became more agile: deliver often and fail fast. Currently 
it would seem that we're hardly delivering at all. For me deliverables 
for any single feature should be a clear spec and examples of using that 
feature.

Regards,
Tom

[1]: https://github.com/OAI/OpenAPI-Specification

Received on Wednesday, 18 May 2016 20:03:36 UTC