Start a Hydra gitbook

[tpluscode]

I'd like to point our attention to recent messages from HTTP APIs by @paul:

We're embarking on the next version of our API [...]. I really want to use Hydra, but it seems like its not ready yet: The "spec" has to be derived from reading a bunch of Github issues, and the few examples I can find seem to be based on various versions of the spec and haven't been updated. It's hard for me to get a feel for what a Hydra API should actually look like.

I really, really want to use Hydra. [...], and its really hard to cobble together the Hydra docs from all over to figure out what it should actually look like.

Another example involves paged collections. The Hydra spec doesn't really mention it, the github repo has a document about collections in "drafts", which links to ISSUE 41, which was resolved in a comment 2 years ago, which updated the hydra.jsonld file, but nothing else. The only example I can find of a paged collection is in one of the "api-platform.com" demo app, and it doesn't even match what was decided in that PR.

---

The Use Cases that we've been working on are a great step forward. We made great progress with some decisions, maybe partially because there are fewer voices.

However, I think that Paul is right on that the knowledge is fragmented and difficult to access.

What would you guys think about starting a separate repo and make the use cases a gitbook? https://hydracg.gitbooks.io/use-cases.

But that could only be the first step. Why not have a a number of books under the HydraCG umbrella?

• /samples -> snippets of actual representations (I think most close to what Paul is asking)
• /heracles.ts -> docs for the client
• /alcaeus -> that's how I intend to rebrand the "old" Heracles which I want to keep developing
• /URSA -> Karol's C# back end
• /argolis -> My C# backend

I know that this will be a big effort but currently we still have limited reach IMO and a fragmented community. Maybe this way we could showcase that Hydra really is a viable alternative to other hypermedia formats?

[lanthaler]

I'm all for it if there's someone driving it and keeping it up to date. I personally unfortunately don't have the time to do it. I can help with reviews though.

[asbjornu]

I agree that something like this is needed. As I very unfortunately haven't had time yet to attend the voice conferences, I feel quite a bit out of the loop, but Github is a good source of information that allows me to understand roughly where things are going.

It would be better to have somewhere with a better overview of where we are, though, and perhaps Gitbook can bee that place. I've never used Gitbook before, so it's difficult for me to say anything for or against it, but let's try and evaluate?

[tpluscode]

@lanthaler would you create a dedicated repo? I was thinking HydraCG/cookbook where I'd start by transferring the use cases from drafts folder. As a second step I'd like to document some current features which we have but aren't really visible - collection paging/filtering, templated links, ordinary links, etc. Just a simple feature+sample representation. Nothing too fancy.

[elf-pavlik]

@tpluscode could you just set it up for this repo here instead of creating another repo?

[tpluscode]

Maybe. Not sure it's possible. First I'd have to become a member of the HydraCG organization

[lanthaler]

Do you know whether it's possible to integrate a GitBook into a website, i.e., hydra-cg.com or does it always stand on its own?

[tpluscode]

@lanthaler It's possible to serve from your own domain. Would this be good enough?

@elf-pavlik It's possible apparently

[elf-pavlik]

It's possible to serve from your own domain. Would this be good enough?

GitBook works very well served from a subdomain, one could easily configure it to work from somethig like https://docs.hydra-cg.com

[lanthaler]

What I had in mind was a much tighter integration of this into the website. People rightly point out that the information about Hydra is currently spread over multiple places. It would be a shame to introduce yet another one. Is there any advantage to using GitBook over, e.g., Hexo or Metalsmith?

[Mec-iS]

Using Github Pages is the right way of keeping things together. Just create a github repository to hold a Markdown repository that is automatically served as a Github Page. That is what we have done to collect our doc in Gtihub here, that is very handy as everybody can update the website with a PR and the README.md file is automatically translated into and HTML page.

[tpluscode]

Gitbook can also be hosted on GH pages

[lanthaler]

IMO the main problem here is not how and where to host it (all use case documents are, e.g., already available on our homepage; example). The thing holding this back is that no one stepped up to drive writing the content.

[Mec-iS]

That's perfectly the point, I am sad to say.

GSOC students needed a lot of general content so we started collecting a general introduction to RDF to let everybody be supported to tackle Hydra with the right tools. I think this could be the right way but I didn't see much interest around it even if I tried to make the repository public in the list and open to contributions. Some beginner students made some great contributions to the Knowledge Base but it cannot be really usefull without all the support from the Community. Please consider amending, adding files or links on https://github.com/HTTP-APIs/http-apis.github.io

[alien-mcl]

There is nothing that prevents anyone in this community to start it. There are already some use cases that could be used for starter, but in case any of you have some experience with hydra already - feel free to move on with this topic. Only thing that worries me is lack of reviewers - both Specifications nad Heracles.ts repositories suffer due to long lasting reviews as there are little contributors willing to comment on the PRs.

[alien-mcl]

I've started this by moving our current use cases to a separate repo within HydraCG space as a started - I'll keep you updated.

[alien-mcl]

I was able to take the mentioned use cases from Specifications repo to it's separate gitbook one. Feel free to fill it with more content :)

[tpluscode]

Okay, closing this. Any further work on the book should go in it's own repo