[GitHub] [camel-kamelets] ReggieCarey commented on issue #673: Kamelet for ElasticSearch Sink provides no mechanism to set indexId or ce-indexId

[GitBox <gi...@apache.org>]

ReggieCarey commented on issue #673:
URL: https://github.com/apache/camel-kamelets/issues/673#issuecomment-1006743329


   I'm glad this issue has sparked a lot of conversation. Consider this some documentation feedback.
   
   1) The user community can't help with the documentation if we have no clue as to how the code works or how it was intended to work.
   2) The links to the kamelet code in the kameletbinding docs usually end up at a GitHub 404 page.
   3) When the links do work, its generally to a yaml file instead of the underlying code that someone could explore to improve the documentation.
   4) The kameletbinding documentation has been largely untouched for at least 6 months - as noted its autogenerated.
   
   Camel-K developers: You've done an excellent job with the product.  I should point out that you'll get much more constructive feedback and increased usage if you bring the documentation up to minimum viable product level. The user community would love to provide constructive feedback but we are working with what appears to be a lot of barriers to success and its due primarily to not being able to understand how these yaml files (KameletBindings) can be used to get something done.  I'll say it again
   
   ```
     steps:
       - ref:
           kind: Kamelet
           apiVersion: camel.apache.org/v1alpha1
           name: insert-field-action
         properties:
           field: The Field
           value: The Value
   ```
   
   is not adequate documentation especially for a product that boasts releasing version 3.11.5 on 31 Dec 2021. But the above is ALL the documentation there is on this capability. Disheartening as it is to hear, the documentation sucks.
   
   What are appropriate values for "field"?  What are legal values for "value"?  Is there a way to pull values from the cloud event headers? Is there a syntax you're abiding by to specify where in a json payload the 'value' will be placed? Is there a templating tool to bring some intelligence to "The Field" and "The Value" strings?
   
   Can I pull values from previous steps of the kameletbinding?  If so, how?
   
   Is there more to the syntax than what is shown in the KameletBinding exemplars? If so, where is it documented?
   
   What can we do? What functionality is present?
   
   What can we not do? What functionality is missing or broken?
   
   Basically, if the feature is not complete, please help us help you.  Tell us what's missing, what's broken, what's planned.  Include a link in the documentation for the feature if not to the specific code implementing the feature, then at least to the repo containing the code.
   
   A note on your documentation audience:
   
   Users coming to Kamelets from a Knative/CloudEvent/Kamel Operator perspective interact with your product via resources deployed into a K8s cluster.  Listing language specific dependencies in this scenario is a bad code smell. What value is there in telling your audience about your various Java dependencies for your code? It may be of value to people writing more in-depth camel integrations or raw custom kamelets but in general your implementation details should not be a concern to people consuming the solution at the K8s integration tier.  Does any of that dependency info in the docs result in something actionable by camel-k users?
   
   I submit that your documentation should focus on how to use all of the nifty things you've built into those Kamelets used in KameletBinding files (the semantics) instead of just what makes a syntactically correct yaml file.
   
   With respect,
   
   Reggie


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org