You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@camel.apache.org by Peter Palaga <pp...@redhat.com> on 2020/04/06 13:54:01 UTC
Ideas how to improve Component, Language, Data format, etc.
descriptions in Camel Catalog
Hi,
The descriptions of components, languages, data formats, etc. in Camel
catalog currently use several inconsistent styles. I wonder whether we
could agree on some common style?
Here an attempt to describe the current state by roughly classifying the
styles and giving some examples. A common style proposal is below.
= "Copy the title" style:
* A Camel GraphQL Component
* Camel Cron Component
= "What it does" style:
* Bridging Eclipse MicroProfile Health with Camel health checks
* Camel metrics exposed with Eclipse MicroProfile Metrics
* Communicates with OData 4.0 services using Apache Olingo OData API.
= "Component for <purpose>" style
* Component for communicating with MQTT message brokers using Eclipse
Paho MQTT Client.
* Component for working with documents stored in MongoDB database.
= "For <purpose>" style
* For calling out to external HTTP servers using Apache HTTP Client 4.x.
* For reading/writing from/to Infinispan distributed key/value store and
data grid.
* For uploading downloading and managing files folders groups
collaborations etc on box DOT com.
= "<title> <kind> is used for <purpose>" style
* JacksonXML data format is used for unmarshal a XML payload to POJO or
to marshal POJO back to XML payload.
* JSon data format is used for unmarshal a JSon payload to POJO or to
marshal POJO back to JSon payload.
= "<title> using <technology>"
* Camel WebSocket using JSR356 (javax)
* Circuit Breaker EIP using Netflix Hystrix
* Distributed tracing using OpenTracing
I think the following basic principles might be useful when trying to
come up with a common style:
(i) Shorter is better. Less/shorter words are faster to read and faster
to understand
(ii) An application of (i): Leave out words and information available
elsewhere in the Catalog record. Esp. do not repeat the title and kind
(component, language, ...) because they are clear from the context. The
same holds for the word "Camel".
(iii) Concentrate on functionality (what it does), because that's what
most users want to know.
"What it does" style seems to be the best match. From the several
flavors, I think the shortest with the plain (imperative) form of the
verb should be prefered - e.g.
new: Unmarshal an XML payload to POJO or marshal a POJO back to XML.
old: JacksonXML data format is used for unmarshal a XML payload to POJO
or to marshal POJO back to XML payload.
The same information, but 6 (~1/3) words less.
WDYT?
Disclaimer: my motivation for this proposal is driven by the fact that
I'd like to re-use the catalog data when scaffolding new Camel Quarkus
extensions, esp. generating pieces of Camel Quarkus documentation and
for generating extension metadata for code.quarkus.io
Thanks,
-- Peter
Re: Ideas how to improve Component, Language, Data format, etc.
descriptions in Camel Catalog
Posted by Peter Palaga <pp...@redhat.com>.
I have filed https://issues.apache.org/jira/browse/CAMEL-14934 and I am
starting to work on it. -- P
On 16/04/2020 17:07, Claus Ibsen wrote:
> Hi
>
> I have started a thread on making it easier to maintain all this
> information in a few single files for all components.
> Which could make it faster and easier to update all of this in one place.
>
> See
> https://camel.465427.n5.nabble.com/Maintaining-information-for-camel-catalog-in-an-easier-way-for-the-huge-number-of-components-we-have-tp5864516.html
>
> On Thu, Apr 9, 2020 at 9:40 AM Claus Ibsen <cl...@gmail.com> wrote:
>>
>> Hi
>>
>> Yes I would like to make those short component descriptions better,
>> especially the ones that just say
>>
>> Camel support for Foo
>>
>> I like the idea of making the description focus on the main
>> functionality and keep it short.
>> Yes we can sometime leave out the project name as its in the title anyway.
>>
>> Currently all the titles are in the class javadoc mainly, and for
>> others in the pom.xml description.
>> So its a bit of "hunt" to find and update them, but surely go for it.
>>
>>
>>
>> On Mon, Apr 6, 2020 at 3:54 PM Peter Palaga <pp...@redhat.com> wrote:
>>>
>>> Hi,
>>>
>>> The descriptions of components, languages, data formats, etc. in Camel
>>> catalog currently use several inconsistent styles. I wonder whether we
>>> could agree on some common style?
>>>
>>> Here an attempt to describe the current state by roughly classifying the
>>> styles and giving some examples. A common style proposal is below.
>>>
>>> = "Copy the title" style:
>>>
>>> * A Camel GraphQL Component
>>> * Camel Cron Component
>>>
>>>
>>> = "What it does" style:
>>>
>>> * Bridging Eclipse MicroProfile Health with Camel health checks
>>> * Camel metrics exposed with Eclipse MicroProfile Metrics
>>> * Communicates with OData 4.0 services using Apache Olingo OData API.
>>>
>>>
>>> = "Component for <purpose>" style
>>>
>>> * Component for communicating with MQTT message brokers using Eclipse
>>> Paho MQTT Client.
>>> * Component for working with documents stored in MongoDB database.
>>>
>>>
>>> = "For <purpose>" style
>>>
>>> * For calling out to external HTTP servers using Apache HTTP Client 4.x.
>>> * For reading/writing from/to Infinispan distributed key/value store and
>>> data grid.
>>> * For uploading downloading and managing files folders groups
>>> collaborations etc on box DOT com.
>>>
>>>
>>> = "<title> <kind> is used for <purpose>" style
>>>
>>> * JacksonXML data format is used for unmarshal a XML payload to POJO or
>>> to marshal POJO back to XML payload.
>>> * JSon data format is used for unmarshal a JSon payload to POJO or to
>>> marshal POJO back to JSon payload.
>>>
>>>
>>> = "<title> using <technology>"
>>>
>>> * Camel WebSocket using JSR356 (javax)
>>> * Circuit Breaker EIP using Netflix Hystrix
>>> * Distributed tracing using OpenTracing
>>>
>>>
>>> I think the following basic principles might be useful when trying to
>>> come up with a common style:
>>>
>>> (i) Shorter is better. Less/shorter words are faster to read and faster
>>> to understand
>>> (ii) An application of (i): Leave out words and information available
>>> elsewhere in the Catalog record. Esp. do not repeat the title and kind
>>> (component, language, ...) because they are clear from the context. The
>>> same holds for the word "Camel".
>>> (iii) Concentrate on functionality (what it does), because that's what
>>> most users want to know.
>>>
>>> "What it does" style seems to be the best match. From the several
>>> flavors, I think the shortest with the plain (imperative) form of the
>>> verb should be prefered - e.g.
>>>
>>> new: Unmarshal an XML payload to POJO or marshal a POJO back to XML.
>>>
>>> old: JacksonXML data format is used for unmarshal a XML payload to POJO
>>> or to marshal POJO back to XML payload.
>>>
>>> The same information, but 6 (~1/3) words less.
>>>
>>> WDYT?
>>>
>>> Disclaimer: my motivation for this proposal is driven by the fact that
>>> I'd like to re-use the catalog data when scaffolding new Camel Quarkus
>>> extensions, esp. generating pieces of Camel Quarkus documentation and
>>> for generating extension metadata for code.quarkus.io
>>>
>>> Thanks,
>>>
>>> -- Peter
>>>
>>
>>
>> --
>> Claus Ibsen
>> -----------------
>> http://davsclaus.com @davsclaus
>> Camel in Action 2: https://www.manning.com/ibsen2
>
>
>
Re: Ideas how to improve Component, Language, Data format, etc.
descriptions in Camel Catalog
Posted by Claus Ibsen <cl...@gmail.com>.
Hi
I have started a thread on making it easier to maintain all this
information in a few single files for all components.
Which could make it faster and easier to update all of this in one place.
See
https://camel.465427.n5.nabble.com/Maintaining-information-for-camel-catalog-in-an-easier-way-for-the-huge-number-of-components-we-have-tp5864516.html
On Thu, Apr 9, 2020 at 9:40 AM Claus Ibsen <cl...@gmail.com> wrote:
>
> Hi
>
> Yes I would like to make those short component descriptions better,
> especially the ones that just say
>
> Camel support for Foo
>
> I like the idea of making the description focus on the main
> functionality and keep it short.
> Yes we can sometime leave out the project name as its in the title anyway.
>
> Currently all the titles are in the class javadoc mainly, and for
> others in the pom.xml description.
> So its a bit of "hunt" to find and update them, but surely go for it.
>
>
>
> On Mon, Apr 6, 2020 at 3:54 PM Peter Palaga <pp...@redhat.com> wrote:
> >
> > Hi,
> >
> > The descriptions of components, languages, data formats, etc. in Camel
> > catalog currently use several inconsistent styles. I wonder whether we
> > could agree on some common style?
> >
> > Here an attempt to describe the current state by roughly classifying the
> > styles and giving some examples. A common style proposal is below.
> >
> > = "Copy the title" style:
> >
> > * A Camel GraphQL Component
> > * Camel Cron Component
> >
> >
> > = "What it does" style:
> >
> > * Bridging Eclipse MicroProfile Health with Camel health checks
> > * Camel metrics exposed with Eclipse MicroProfile Metrics
> > * Communicates with OData 4.0 services using Apache Olingo OData API.
> >
> >
> > = "Component for <purpose>" style
> >
> > * Component for communicating with MQTT message brokers using Eclipse
> > Paho MQTT Client.
> > * Component for working with documents stored in MongoDB database.
> >
> >
> > = "For <purpose>" style
> >
> > * For calling out to external HTTP servers using Apache HTTP Client 4.x.
> > * For reading/writing from/to Infinispan distributed key/value store and
> > data grid.
> > * For uploading downloading and managing files folders groups
> > collaborations etc on box DOT com.
> >
> >
> > = "<title> <kind> is used for <purpose>" style
> >
> > * JacksonXML data format is used for unmarshal a XML payload to POJO or
> > to marshal POJO back to XML payload.
> > * JSon data format is used for unmarshal a JSon payload to POJO or to
> > marshal POJO back to JSon payload.
> >
> >
> > = "<title> using <technology>"
> >
> > * Camel WebSocket using JSR356 (javax)
> > * Circuit Breaker EIP using Netflix Hystrix
> > * Distributed tracing using OpenTracing
> >
> >
> > I think the following basic principles might be useful when trying to
> > come up with a common style:
> >
> > (i) Shorter is better. Less/shorter words are faster to read and faster
> > to understand
> > (ii) An application of (i): Leave out words and information available
> > elsewhere in the Catalog record. Esp. do not repeat the title and kind
> > (component, language, ...) because they are clear from the context. The
> > same holds for the word "Camel".
> > (iii) Concentrate on functionality (what it does), because that's what
> > most users want to know.
> >
> > "What it does" style seems to be the best match. From the several
> > flavors, I think the shortest with the plain (imperative) form of the
> > verb should be prefered - e.g.
> >
> > new: Unmarshal an XML payload to POJO or marshal a POJO back to XML.
> >
> > old: JacksonXML data format is used for unmarshal a XML payload to POJO
> > or to marshal POJO back to XML payload.
> >
> > The same information, but 6 (~1/3) words less.
> >
> > WDYT?
> >
> > Disclaimer: my motivation for this proposal is driven by the fact that
> > I'd like to re-use the catalog data when scaffolding new Camel Quarkus
> > extensions, esp. generating pieces of Camel Quarkus documentation and
> > for generating extension metadata for code.quarkus.io
> >
> > Thanks,
> >
> > -- Peter
> >
>
>
> --
> Claus Ibsen
> -----------------
> http://davsclaus.com @davsclaus
> Camel in Action 2: https://www.manning.com/ibsen2
--
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2
Re: Ideas how to improve Component, Language, Data format, etc.
descriptions in Camel Catalog
Posted by Claus Ibsen <cl...@gmail.com>.
Hi
Yes I would like to make those short component descriptions better,
especially the ones that just say
Camel support for Foo
I like the idea of making the description focus on the main
functionality and keep it short.
Yes we can sometime leave out the project name as its in the title anyway.
Currently all the titles are in the class javadoc mainly, and for
others in the pom.xml description.
So its a bit of "hunt" to find and update them, but surely go for it.
On Mon, Apr 6, 2020 at 3:54 PM Peter Palaga <pp...@redhat.com> wrote:
>
> Hi,
>
> The descriptions of components, languages, data formats, etc. in Camel
> catalog currently use several inconsistent styles. I wonder whether we
> could agree on some common style?
>
> Here an attempt to describe the current state by roughly classifying the
> styles and giving some examples. A common style proposal is below.
>
> = "Copy the title" style:
>
> * A Camel GraphQL Component
> * Camel Cron Component
>
>
> = "What it does" style:
>
> * Bridging Eclipse MicroProfile Health with Camel health checks
> * Camel metrics exposed with Eclipse MicroProfile Metrics
> * Communicates with OData 4.0 services using Apache Olingo OData API.
>
>
> = "Component for <purpose>" style
>
> * Component for communicating with MQTT message brokers using Eclipse
> Paho MQTT Client.
> * Component for working with documents stored in MongoDB database.
>
>
> = "For <purpose>" style
>
> * For calling out to external HTTP servers using Apache HTTP Client 4.x.
> * For reading/writing from/to Infinispan distributed key/value store and
> data grid.
> * For uploading downloading and managing files folders groups
> collaborations etc on box DOT com.
>
>
> = "<title> <kind> is used for <purpose>" style
>
> * JacksonXML data format is used for unmarshal a XML payload to POJO or
> to marshal POJO back to XML payload.
> * JSon data format is used for unmarshal a JSon payload to POJO or to
> marshal POJO back to JSon payload.
>
>
> = "<title> using <technology>"
>
> * Camel WebSocket using JSR356 (javax)
> * Circuit Breaker EIP using Netflix Hystrix
> * Distributed tracing using OpenTracing
>
>
> I think the following basic principles might be useful when trying to
> come up with a common style:
>
> (i) Shorter is better. Less/shorter words are faster to read and faster
> to understand
> (ii) An application of (i): Leave out words and information available
> elsewhere in the Catalog record. Esp. do not repeat the title and kind
> (component, language, ...) because they are clear from the context. The
> same holds for the word "Camel".
> (iii) Concentrate on functionality (what it does), because that's what
> most users want to know.
>
> "What it does" style seems to be the best match. From the several
> flavors, I think the shortest with the plain (imperative) form of the
> verb should be prefered - e.g.
>
> new: Unmarshal an XML payload to POJO or marshal a POJO back to XML.
>
> old: JacksonXML data format is used for unmarshal a XML payload to POJO
> or to marshal POJO back to XML payload.
>
> The same information, but 6 (~1/3) words less.
>
> WDYT?
>
> Disclaimer: my motivation for this proposal is driven by the fact that
> I'd like to re-use the catalog data when scaffolding new Camel Quarkus
> extensions, esp. generating pieces of Camel Quarkus documentation and
> for generating extension metadata for code.quarkus.io
>
> Thanks,
>
> -- Peter
>
--
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2