search

eclipse-kuksa / kuksa-website

Sources of the Kuksa website
Apache License 2.0
2 stars 12 forks source link

Write a getting started for the Website #54

Closed eriksven closed 1 year ago

eriksven commented 1 year ago

The idea is to have a getting started guide for the interaction with the Kuksa Databroker including the CLI and SDK.

I am aware of the documentations in https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker or https://github.com/eclipse/kuksa.val/tree/master/kuksa-client/docs .

But I am more thinking about an overview and hand-on description referencing the other documentation.

@SebastianSchildt @lukasmittag what do you think?

lukasmittag commented 1 year ago

I do not know how much sense this makes. The way I see it that our repository is more popular than the website itself. I could be wrong. Either way a page how to get started could not hurt. Like we saw at the PS Hacksthon it would be good to have a hello world example. But we need to define a scope for the getting started. Is it just for the VAL or do we want to include feeders/providers and services too?

SebastianSchildt commented 1 year ago

The "kind of" documentation you search is likely this or an extended take on it https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md

If you did not find it, discoverability might be an issue. I think we should NOT use website (as in "this repo") to write some documentation on the website. we had it once (i think the fiels are still here), and is was disconnected form code, useless and outdated.

What I could imagine, if there were some way to transform/adapt all those mrkdowns here https://github.com/eclipse/kuksa.val/tree/master/doc into some form + CI that it is also Hugo generated. That might be seperate from the "main" marketing page (only linked prominently). That would go more in the direction of what Velocitas is doing https://websites.eclipseprojects.io/velocitas/docs/

Actually the issue was (as usual) "lack of time" in the team. If you can remix existing documentation and whip some static site generator/CI on top to turn it into something more "approachable" that would be appreciated, however form Dev perspective is is important I think, that all that needs to be done to keep this updated, updating markdown files in the main repo

eriksven commented 1 year ago

Yes, https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md is a very good foundation for what I was thinking of.

My target audience would be interested developers who have seen the sticker and want to know what is behind that. So I would add a paragraph introducing the general idea of abstraction through VSS and the data broker.

I get your concerns to have multiple documentations which will diverge as soon as you merge the PR ;) . So an approach could be to link the Markdown file in GitHub from the website and keep the Markdown as single source of truth.

Regarding the "lack of time", I would volunteer to spend some time on adding the reference to the website and looking into how the site generator could use the markdown files from the main repo. The intention of creating this issue was therefore mostly to see if there is interest or if I am missing parallel activities.