I waited about 2 weeks to allow enough time for feedback. There was a good amount of initial discussion on the document mostly in the form of proposals to enhance the initial plan. There were zero negative comments and nobody opposed the plan.

The aim is to add a "Tracing" entry as a "stage 2", but wasn't sure whether this meant releasing a version of the website without it first, and then introduce it as a separate step?

A general comment - perhaps we should drop the "Hawkular" part from each component - so then we simply have "Metrics", "Alerts" and "Tracing"?

On Tue, Jul 4, 2017 at 8:22 AM, Heiko Rupp <hrupp(a)redhat.com&gt; wrote: > Hey, > > On 3 Jul 2017, at 23:42, Stefan Negrea wrote: > > > I waited about 2 weeks to allow enough time for feedback. There was a > > good amount of initial discussion on the document mostly in the form > > of proposals to enhance the initial plan. There were zero negative > > comments and nobody opposed the plan. > > I know I did not chime in on the document, so have no right > to complain now :-) > > I think though that the removal of Hawkular Services is wrong. > It may indeed at the moment only exist for that one consumer, > which is ManageIQ, but not listing it is in my opinion also > confusing. Instead of removing it, we should perhaps better > educate visitors of the web site (in a graphical way?) how this > relates to the other projects. > Similar to Tracing. This is no longer Hawkular APM, so it is right > not to list Hawkular APM, but so far Tracing folks are still under the > Hawkular umbrella and the blog contains a lot of content about it. > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

On Tue, Jul 4, 2017 at 9:22 AM, Heiko Rupp <hrupp(a)redhat.com&gt; wrote: > I think though that the removal of Hawkular Services is wrong. > It may indeed at the moment only exist for that one consumer, > which is ManageIQ, but not listing it is in my opinion also > confusing. Instead of removing it, we should perhaps better > educate visitors of the web site (in a graphical way?) how this > relates to the other projects. > I'm sure we have stats on what people downloads the most... is it metrics/alerts standalone, or services? We could take it in consideration. Having it removed from the menu really makes things clearer, I think, but on the other hand we could find ways not to make it completely off the radars. For instance, adding something at the top of metrics/alerts install page: "Looking for integrated metrics + alerting? Check out Hawkular Services". Another thing about services disappearing: the shame is that IMO it currently has a better-written doc than metrics (the quickstart guide is good, the installation guide is better than metric's simple link to github).

_______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

Agreed, Hawkular Services need more love, not to disappear. It may be renamed to "Hawkular ManageIQ Provider" on the website if that helps with clarity, but shouldn't disappear. Also there is no quickstart anymore, it's very rough for people.

wrote:

wrote:

wrote:

wrote:

wrote:

wrote:

Alerts don't include Metrics, but the opposite is true for a few releases now (it has not always been the case). Yes, Hawkular Services is/was the go-to place since it had everything included (Alerting, Metrics, Inventory(RIP), EAP Agent, Command Gateway, "glue code")... The EAP Agent and Command Gateway are pretty much related to ManageIQ so we could make the switch and claim it is for ManageIQ (and work in that direction) but then we first need an easy way to consume Metrics+Alerting, currently there is no binary for that (No Zip, No Docker) which has been missing for a whiile, there is also no quickstart except for Alerting. Thomas On Tue, Jul 4, 2017 at 7:55 PM, Josejulio Martinez Magana <jmartine(a)redhat.com <mailto:jmartine@redhat.com>> wrote: i might be wrong, but services = metrics (with alerts) + agent + glue code between agent and alerts(notifications) + status page On Tue, Jul 4, 2017 at 12:43 PM, Edgar Hernandez Garcia <ehernand(a)redhat.com <mailto:ehernand@redhat.com>> wrote: Yes, its a little confusing. May be I'm wrong in that alerts include metrics (I wrote that only trusting my memory). If I'm wrong, it's ok to keep them as separate releases. But the confusion remains between metrics and services, because it's not very clear how you choose between metrics and services. On Tue, Jul 4, 2017 at 12:24 PM, Josejulio Martinez Magana <jmartine(a)redhat.com <mailto:jmartine@redhat.com>> wrote: I didn't know alerts included metrics (I knew that metrics included alerts) If they include each other, why not call them as a whole instead as the parts? Is confusing for me that they are two distributions and that each that are mutually included in each other. What's the difference? On Tue, Jul 4, 2017 at 12:04 PM, Edgar Hernandez Garcia <ehernand(a)redhat.com <mailto:ehernand@redhat.com>> wrote: On Tue, Jul 4, 2017 at 11:55 AM, Edgar Hernández <ehernand(a)redhat.com <mailto:ehernand@redhat.com>> wrote: And, now, starting with "metrics 0.27.0 <https://github.com/hawkular/hawkular-metrics/releases/tag/0.27.0>" I can see that metrics also includes alerts. I just realized that alerts is included with metrics even with previous releases. So, both parts have been shipping the other part for a while. Now, it's got weirder for me. _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org <mailto:hawkular-dev@lists.jboss.org> https://lists.jboss.org/mailman/listinfo/hawkular-dev <https://lists.jboss.org/mailman/listinfo/hawkular-dev> _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org <mailto:hawkular-dev@lists.jboss.org> https://lists.jboss.org/mailman/listinfo/hawkular-dev <https://lists.jboss.org/mailman/listinfo/hawkular-dev> _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org <mailto:hawkular-dev@lists.jboss.org> https://lists.jboss.org/mailman/listinfo/hawkular-dev <https://lists.jboss.org/mailman/listinfo/hawkular-dev> _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org <mailto:hawkular-dev@lists.jboss.org> https://lists.jboss.org/mailman/listinfo/hawkular-dev <https://lists.jboss.org/mailman/listinfo/hawkular-dev> _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

I meant to share this earlier (my fault for not forwarding it a week or two ago). One of the Red Hat Content Strategists attended OSCON back in May and wrote up an awesome blog post (with examples) about a panel on how documentation can help the adoption of your project. TLDR: our web site needs to explain Hawkular to anyone that lands on it, and guide them from beginner content written for someone who has never heard of Hawkular to more advanced content. Right now? The bare screen with a couple of buttons and a tag cloud is not an improvement on the previous site, which at least had an overview, getting started, and explained the features. We need a good description of what the Hawkular project is and what it can do for you. If we were to write a new Getting Started or Quick Start guide for Hawkular, where would we start? Would we need one for each component? *** https://mojo.redhat.com/people/nengard/blog/2017/05/ 11/oscon-how-documentation-can-help-in-the-adoption-of-your-project For those not on Mojo, here's the blog post text: *OSCON : How documentation can help in the adoption of your project* Ben Hall from Katacoda and Ocelot Uproar gave an awesome talk at OSCON about a topic near and dear to my heart - documentation! Ben wanted us to know that the journey to documentation begins before you think, it's not just the 'documentation' but it's the examples and demos on your website. It's actually the first page of your website! Users look at these things before they read the guides. A big mistake we make in software is that we often give people the product to download and then give them access to the entire manual without any steps in between. Instead, we should approach documentation in incremental steps to build the user's confidence. Everyone is super busy and stressed, but they're motivated when they come to your project site and you don't want to add additional stress and de-motivate them with your documentation or lack thereof. This is why almost every intro to computer science class teaches a "Hello world" example. It has a low barrier to entry and is easy for folks to learn. We want our documentation to get folks to a level where they are confident in acquiring more knowledge. Think of documentation in the following steps: 1. Exploration 2. Getting Started 3. Onboarding/Problem Solving 4. Guidance and Discovery 5. Reference *Step 1 Exploration* Imagine that someone has just landed on your GitHub site and they're interested in learning more. What do you have there to hook them in and make them feel comfortable? This site is the first step of our documentation and you want to answer the customer's question of 'why should I care?' easily so that you can pull the user in further. Some examples that Ben provided us with of sites that handle this well are: - Kubernetes [https://kubernetes.io/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fkubernetes.i...>] site is very clear right away. - Project Calico [https://www.projectcalico.org/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fwww.projectc...>] takes one line to explain what their purpose is right at the top of the page - Kotlin [https://kotlinlang.org/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fkotlinlang.o...>] is an example of how to get folks to feel confident about the product before downloading it. On the other end of things, the Docker site is a less clear example. The first line is about getting started, but if I don't know what Docker is, why do I want to get started? The lines at the top moves so the next thing you see is about getting certified which is way past the level your new users are at. It takes 4 pages of scrolling before you learn what Docker is. This is how you lose new customers. This was just one example from the speaker, but many companies do this. *Step 2 Getting Started* Now that you got your potential customers to care about your project. Next, you need to show them that your product is just what they need to solve their problem. You have about 9 minutes here before you lose a motivated user's interest. A great example of hooking the user in is Stripe [https://stripe.com/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fstripe.com%2F>]. They have a very clear getting started guide complete with code snippets. They also include small discreet sections that are easy to digest and follow. OpenShift [https://www.openshift.org/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fwww.openshif...>] is another great example of easy to access getting started information. The site tells the user everything they need to know right when they need to know it. *Step 3: Onboarding* The user now wants to use your product. You want to get them up and running easily. A good example of this is Mixpanel [https://mixpanel.com/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fmixpanel.com%2F>]. They have the documentation embedded right into the portal and don't have long lengthy documentation that you have to read. They make the process engaging for the user. You want to get people over the first hurdle of seeing the system in action. Jump right into the process. *Stage 4: Guidance and Discovery* Now that you have the customer all set up and running, they're probably interested in what other problems your product can solve for them. The users already have the difficult parts done, they got started, they have the system up and running, and now they want to know what else is possible. Twilio [https://www.twilio.com/docs/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fwww.twilio.c...>] has a great example of this. You can easily pick what documentation is best for you from their handy header. They provide you with screenshots, videos, text content, and where to go next. This stage is a good place to start promoting your community. Include options to explore your community and show what people are doing with your product. *Stage 5: Reference* Now your users want to be experts. Now users will look for your in-depth documentation. *Given these steps, who creates documentation best?* Lego! Lego has the best documentation of all. Think about it, they don't need to explain anything using words in their documentation, it's all pictures. They not only help you follow the rules, but they also encourage you to be creative. They have a website [https://ideas.lego.com/ <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fideas.lego.c...>] where they let people publish their own creations. This makes the community feel more passionate. JULIE STICKLER TECHNICAL WRITER Red Hat <https://www.redhat.com/> Westford – 3S353 jstickle(a)redhat.com T: 1(978)-399-0463-(812-0463) IRC: jstickler On Wed, Jul 5, 2017 at 10:39 AM, Jay Shaughnessy <jshaughn(a)redhat.com&gt; wrote: > > The two most consumable pieces of hawkular are Standalone Alerts and > Standalone Metrics. And these should be featured most prominently on the > web site (imo). Because the "Hawkular" prefix is so cumbersome to say, I > think we should typically call these things "hAlerts" and "hMetrics". I > like the idea of also having the home page lead to other things Hawkular, > such as Tracing, MIQ Provider (much better than calling it Hawkular > Services), HawkFX, The ruby gems, etc... The fact that Metrics bundles > Alerts enhances the Metrics offering but remember that this is primarily a > metrics solution. HAlerts should be featured independently as a > standalone, pluggable solution for federated alerting. > > As mentioned prior: > > - hServices really has only one consumer, MIQ, and should likely just > be presented in that way. > - hAlerts does *not* bundle metrics. > - we should probably take a look at the docker hub and make sure it > is coherent > > > On 7/5/2017 1:47 AM, Thomas Heute wrote: > > Alerts don't include Metrics, but the opposite is true for a few releases > now (it has not always been the case). > > Yes, Hawkular Services is/was the go-to place since it had everything > included (Alerting, Metrics, Inventory(RIP), EAP Agent, Command Gateway, > "glue code")... > > The EAP Agent and Command Gateway are pretty much related to ManageIQ so > we could make the switch and claim it is for ManageIQ (and work in that > direction) but then we first need an easy way to consume Metrics+Alerting, > currently there is no binary for that (No Zip, No Docker) which has been > missing for a whiile, there is also no quickstart except for Alerting. > > Thomas > > On Tue, Jul 4, 2017 at 7:55 PM, Josejulio Martinez Magana < > jmartine(a)redhat.com&gt; wrote: > >> i might be wrong, but services = metrics (with alerts) + agent + glue >> code between agent and alerts(notifications) + status page >> >> On Tue, Jul 4, 2017 at 12:43 PM, Edgar Hernandez Garcia < >> ehernand(a)redhat.com&gt; wrote: >> >>> Yes, its a little confusing. >>> >>> May be I'm wrong in that alerts include metrics (I wrote that only >>> trusting my memory). If I'm wrong, it's ok to keep them as separate >>> releases. But the confusion remains between metrics and services, because >>> it's not very clear how you choose between metrics and services. >>> >>> >>> On Tue, Jul 4, 2017 at 12:24 PM, Josejulio Martinez Magana < >>> jmartine(a)redhat.com&gt; wrote: >>> >>>> I didn't know alerts included metrics (I knew that metrics included >>>> alerts) >>>> If they include each other, why not call them as a whole instead as >>>> the parts? >>>> >>>> Is confusing for me that they are two distributions and that each that >>>> are mutually included in each other. What's the difference? >>>> >>>> On Tue, Jul 4, 2017 at 12:04 PM, Edgar Hernandez Garcia < >>>> ehernand(a)redhat.com&gt; wrote: >>>> >>>>> >>>>> >>>>> On Tue, Jul 4, 2017 at 11:55 AM, Edgar Hernández <ehernand(a)redhat.com >>>>> > wrote: >>>>> >>>>>> >>>>>> And, now, starting with "metrics 0.27.0 >>>>>> <https://github.com/hawkular/hawkular-metrics/releases/tag/0.27.0>" >>>>>> I can see that metrics also includes alerts. >>>>>> >>>>>> >>>>> I just realized that alerts is included with metrics even with >>>>> previous releases. So, both parts have been shipping the other part for a >>>>> while. Now, it's got weirder for me. >>>>> >>>>> >>>>> _______________________________________________ >>>>> hawkular-dev mailing list >>>>> hawkular-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>>>> >>>>> >>>> >>>> _______________________________________________ >>>> hawkular-dev mailing list >>>> hawkular-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>>> >>>> >>> >>> _______________________________________________ >>> hawkular-dev mailing list >>> hawkular-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>> >>> >> >> _______________________________________________ >> hawkular-dev mailing list >> hawkular-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hawkular-dev >> >> > > > _______________________________________________ > hawkular-dev mailing listhawkular-dev@lists.jboss.orghttps://lists.jboss.org/mailman/listinfo/hawkular-dev > > > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

Thank you, Stefan Negrea On Tue, Jul 4, 2017 at 11:55 AM, Edgar Hernández <ehernand(a)redhat.com&gt; wrote: > > On 07/04/2017 02:41 AM, Thomas Heute wrote: > > Agreed, Hawkular Services need more love, not to disappear. > It may be renamed to "Hawkular ManageIQ Provider" on the website if that > helps with clarity, but shouldn't disappear. > > Also there is no quickstart anymore, it's very rough for people. > > > > What!? This really comes as a surprise for me. All this time my thinking > was that "services" was the thing bundling all parts together and, because > of the quickstarts, I believed that "services" was the preferred way to get > Hawkular. This idea is further supported by exploring the DockerHub, where > only images of Hawkular-services are available. > > Also, right after "Inventory" got removed, "services" and "alerts" were > somewhat redundant for me because "metrics" is included with "alerts" (and > "services" also includes both). And, now, starting with "metrics 0.27.0 > <https://github.com/hawkular/hawkular-metrics/releases/tag/0.27.0>" I > can see that metrics also includes alerts. So, the thing looks more > redundant now. But with time I learned that "services" provides the > operations api, used by ManageIQ. I don't know if there are other features > provided by "services". But those extra features are not documented in the > website and people new to Hawkular won't realize what's the idea behind > "services". > > - Edgar. > Hawkular Metrics started bundling Alerting in October of last year and there are no plans to not bundle it.

We need to make a differentiation between the components (Alerting, Metrics, Trancing) and their integration into other projects. Hawkular Services is a specific integration for ManageIQ. We need to adjust the content around the core components to be able to build a community around the core components. The integrations are just delivery methods for these components. The integration of Hawkular Metrics and Alerting (there is a special bundle for that just like Hawkular Services) in OpenShift Origin has been used a lot more people than Hawkular Services ever was. Yet it is nowhere featured or discussed. We need to refocus the front page on the core components. Hawkular Services or Hawkular Metrics & Alerting OpenShift Origin (or other future integrations) should be mentioned but in another section. > > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

Hey, On 3 Jul 2017, at 23:42, Stefan Negrea wrote: > I waited about 2 weeks to allow enough time for feedback. There was a > good amount of initial discussion on the document mostly in the form > of proposals to enhance the initial plan. There were zero negative > comments and nobody opposed the plan. I know I did not chime in on the document, so have no right to complain now :-)

I think though that the removal of Hawkular Services is wrong. It may indeed at the moment only exist for that one consumer, which is ManageIQ, but not listing it is in my opinion also confusing. Instead of removing it, we should perhaps better educate visitors of the web site (in a graphical way?) how this relates to the other projects. Similar to Tracing. This is no longer Hawkular APM, so it is right not to list Hawkular APM, but so far Tracing folks are still under the Hawkular umbrella and the blog contains a lot of content about it.

_______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev