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 <claus.ib...@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 <ppal...@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
