search

kroxylicious / kroxylicious.github.io

kroxylicious.io org page
0 stars 8 forks source link

Starting some use-case/overview documentation #25

Closed k-wall closed 6 months ago

k-wall commented 6 months ago

We want some use-case documentation that helps those in the "key decisions maker" role understand Kroxylicious and the problems it can solve.

k-wall commented 6 months ago

@SamBarker @tombentley @robobario I'm not asking for a detailed review at this stage, more feedback on whether this pitch I am taking is broadly the right one. Thoughts, comments, criticism welcome!

k-wall commented 6 months ago

What is the target persona for these use case docs? Decision maker types?

Yes, key decision makers is really the target audience.

If so then I think this is a good start and keeping things nice and generic is good. I'm just wondering how we then go onto land the much more developer / implementor specific details.

I decided to start with this use-case documentation rather than https://github.com/kroxylicious/kroxylicious/issues/787 so I could resist the temptation to include the this content there. That's going to describe how to use the feature.

I'm just wondering how we then go onto land the much more developer / implementor specific details.

could you give an example of the sort of thing you have in mind?

My intent with the use-case documentation is to start small. We can grow it as we go.

SamBarker commented 6 months ago

could you give an example of the sort of thing you have in mind?

The decision maker content is high level and at some point we need to go into the details about how we handle keys and the how we provide a decrypt-ability guarantee etc. My usual problem is landing on the high level stuff and then repeatedly saying "yes but how?".

To be clear I think you're right to start high level but having a plan for how we connect to the details.

It could be as simple as a sentence saying see the XXX section for details on how we deliver this.

My intent with the use-case documentation is to start small. We can grow it as we go.

Yes definitely, I don't want to derail or discourage that!

k-wall commented 6 months ago

Hey Keith, looks like a good start, and definitely content worth having on the site.

Most of my feedback is below in the comments, but one other thing I wanted to mention is that I'm not quite sure about the (rendered) layout of the use cases page. I can't put my finger on what exactly is bothering me about it, and I'm also not sure what specifically I would change about it (which is why I'm mentioning it here and not below) so it's absolutely not a blocker, but I might try pushing some CSS around at some point and see if I can fix whatever it is about it that's bothering me.

HTML/CSS and related technologies aren't my strong suit. I haven't used Jekyll before. Feel free to collaborate on this PR and push things in the right direction. Push direct to the branch if you like.

I love to hear your comments on the content too.

k-wall commented 6 months ago

@SamBarker @gracegrimwood thanks for the feedback so far. I'm hoping what I have is coming close to being mergeable. I'm not intending to add much more content for this PR.

My intention is that we continue to iterate on it in future PRs. I see multi tenant etc being a separate PR too.

gracegrimwood commented 6 months ago

Hi @k-wall, I've submitted a PR for this branch to move the use-cases that just contain "To Do" to a drafts folder (so they won't be rendered on the site), and also adjust the layout of the use-cases page to make things align a bit better.

k-wall commented 6 months ago

Thanks @SamBarker I merge as it stands and open issues for the outstanding comments.