<div dir="ltr">Thank you Julie for these guidelines. I think the problem we have here is that we're focused on a "strategic" decision (which is: put focus on standalone components) without considering the loss in the documentation organization. If we switch the focus from hServices to hMetrics/hAlerts we should bring their documentation to at least the same level and we need an equivalent "getting started" than this one [1] (eventually we could just adapt it to hMetrics alone and hAlerts alone). The same applies for the installation guide [2].<div><br></div><div>For the front page, I believe it's just the first step and we definitely need to replace the removed content with something else. Probably the PR should be merged in another branch so that the website is not affected during these re-design.</div><div><br></div><div><div>[1] <a href="http://www.hawkular.org/hawkular-services/docs/quickstart-guide/">http://www.hawkular.org/hawkular-services/docs/quickstart-guide/</a></div><div>[2] <a href="http://www.hawkular.org/hawkular-services/docs/installation-guide/">http://www.hawkular.org/hawkular-services/docs/installation-guide/</a></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jul 5, 2017 at 10:29 PM, Julie Stickler <span dir="ltr"><<a href="mailto:jstickle@redhat.com" target="_blank">jstickle@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_default" style="font-family:verdana,sans-serif">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.</div><div class="gmail_default" style="font-family:verdana,sans-serif"><br></div><div class="gmail_default" style="font-family:verdana,sans-serif">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.</div><div class="gmail_default" style="font-family:verdana,sans-serif"><br></div><div class="gmail_default" style="font-family:verdana,sans-serif">We need a good description of what the Hawkular project is and what it can do for you.</div><div class="gmail_default" style="font-family:verdana,sans-serif"><br></div><div class="gmail_default" style="font-family:verdana,sans-serif">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?</div><div class="gmail_default" style="font-family:verdana,sans-serif"><br></div><div class="gmail_default" style="font-family:verdana,sans-serif">***</div><div class="gmail_default" style="font-family:verdana,sans-serif"><br></div><div class="gmail_default"><font face="verdana, sans-serif"><a href="https://mojo.redhat.com/people/nengard/blog/2017/05/11/oscon-how-documentation-can-help-in-the-adoption-of-your-project" target="_blank">https://mojo.redhat.com/<wbr>people/nengard/blog/2017/05/<wbr>11/oscon-how-documentation-<wbr>can-help-in-the-adoption-of-<wbr>your-project</a></font><br></div><div class="gmail_default"><font face="verdana, sans-serif"><br></font></div><div class="gmail_default"><span style="font-family:verdana,sans-serif">For those not on Mojo, here's the blog post text:</span><font face="verdana, sans-serif"><br></font></div><div class="gmail_default">
<p><b>OSCON : How documentation can help in the adoption of your
project</b></p>
<p>Ben Hall from Katacoda and Ocelot Uproar gave an awesome talk at
OSCON about a topic near and dear to my heart - documentation!</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Think of documentation in the following steps:</p>
<ol>
<li>
<p style="margin-bottom:0in">Exploration</p>
</li><li>
<p style="margin-bottom:0in">Getting Started</p>
</li><li>
<p style="margin-bottom:0in">Onboarding/Problem Solving</p>
</li><li>
<p style="margin-bottom:0in">Guidance and Discovery</p>
</li><li>
<p>Reference</p>
</li></ol>
<p style="border:none;padding:0in"> </p>
<p><strong>Step 1 Exploration</strong></p>
<p>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.</p>
<p>Some examples that Ben provided us with of sites that handle this
well are:</p>
<ul>
<li>
<p style="margin-bottom:0in">Kubernetes
[<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fkubernetes.io%2F" target="_blank">https://kubernetes.io/</a>]
site is very clear right away.</p>
</li><li>
<p style="margin-bottom:0in">Project Calico
[<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fwww.projectcalico.org%2F" target="_blank">https://www.projectcalico.<wbr>org/</a>]
takes one line to explain what their purpose is right at the top of
the page</p>
</li><li>
<p>Kotlin [<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fkotlinlang.org%2F" target="_blank">https://kotlinlang.org/</a>]
is an example of how to get folks to feel confident about the
product before downloading it.</p></li></ul>
<p>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. </p>
<p><strong>Step 2 Getting Started</strong> </p>
<p>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. </p>
<p>A great example of hooking the user in is Stripe
[<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fstripe.com%2F" target="_blank">https://stripe.com/</a>].
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.</p>
<p>OpenShift [<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fwww.openshift.org%2F" target="_blank">https://www.openshift.org/</a>]
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.</p>
<p><strong>Step 3: Onboarding</strong></p>
<p>The user now wants to use your product. You want to get them up
and running easily. </p>
<p>A good example of this is Mixpanel [<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fmixpanel.com%2F" target="_blank">https://mixpanel.com/</a>].
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.</p>
<p>You want to get people over the first hurdle of seeing the system
in action. Jump right into the process.</p>
<p><strong>Stage 4: Guidance and Discovery</strong> </p>
<p>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.</p>
<p>Twilio [<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fwww.twilio.com%2Fdocs%2F" target="_blank">https://www.twilio.com/docs/</a>]
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.</p>
<p>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. </p>
<p><strong>Stage 5: Reference</strong> </p>
<p>Now your users want to be experts. Now users will look for your
in-depth documentation.</p>
<p><strong>Given these steps, who creates documentation best?</strong></p>
<p>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
[<a href="https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fideas.lego.com%2F" target="_blank">https://ideas.lego.com/</a>]
where they let people publish their own creations. This makes the
community feel more passionate.</p></div></div><div class="gmail_extra"><br clear="all"><div><div class="m_1001546689258592143gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><p style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-weight:bold;margin:0px;padding:0px;font-size:14px;text-transform:uppercase"><span>JULIE</span> <span>STICKLER</span></p><p style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:10px;margin:0px 0px 4px;text-transform:uppercase"><span>TECHNICAL WRITER</span></p><p style="font-family:overpass,sans-serif;margin:0px;font-size:10px;color:rgb(153,153,153)"><a href="https://www.redhat.com/" style="color:rgb(0,136,206);margin:0px" target="_blank">Red Hat <span><br><br></span></a></p><p style="font-size:10px;margin:0px">Westford – 3S353</p><p style="font-family:overpass,sans-serif;margin:0px 0px 6px;font-size:10px;color:rgb(153,153,153)"><span style="margin:0px;padding:0px"><a href="mailto:jstickle@redhat.com" style="color:rgb(0,136,206);margin:0px" target="_blank">jstickle@redhat.com</a> </span> <span>T: <a href="tel:1(978)-399-0463-(812-0463)" style="color:rgb(0,136,206);margin:0px" target="_blank">1(978)-399-0463-(812-<wbr>0463)</a> </span> <span>IRC: <span>jstickler</span></span></p></div>
</div></div></div></div></div></div><div><div class="h5">
<br><div class="gmail_quote">On Wed, Jul 5, 2017 at 10:39 AM, Jay Shaughnessy <span dir="ltr"><<a href="mailto:jshaughn@redhat.com" target="_blank">jshaughn@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div text="#000000" bgcolor="#FFFFFF">
<br>
<font face="Calibri">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.</font><br>
<br>
As mentioned prior:<br>
<ul>
<li>hServices really has only one consumer, MIQ, and should likely
just be presented in that way.</li>
<li>hAlerts does *not* bundle metrics.</li>
<li>we should probably take a look at the docker hub and make sure
it is coherent<br>
</li>
</ul><div><div class="m_1001546689258592143h5">
<br>
<div class="m_1001546689258592143m_-1247458806721969361moz-cite-prefix">On 7/5/2017 1:47 AM, Thomas Heute
wrote:<br>
</div>
<blockquote type="cite">
<div dir="ltr">Alerts don't include Metrics, but the opposite is
true for a few releases now (it has not always been the case).
<div><br>
</div>
<div>Yes, Hawkular Services is/was the go-to place since it had
everything included (Alerting, Metrics, Inventory(RIP), EAP
Agent, Command Gateway, "glue code")...</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>Thomas</div>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Tue, Jul 4, 2017 at 7:55 PM,
Josejulio Martinez Magana <span dir="ltr"><<a href="mailto:jmartine@redhat.com" target="_blank">jmartine@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">
<div class="gmail_extra">i might be wrong, but services =
metrics (with alerts) + agent + glue code between agent
and alerts(notifications) + status page</div>
<div>
<div class="m_1001546689258592143m_-1247458806721969361h5">
<div class="gmail_extra"><br>
<div class="gmail_quote">On Tue, Jul 4, 2017 at
12:43 PM, Edgar Hernandez Garcia <span dir="ltr"><<a href="mailto:ehernand@redhat.com" target="_blank">ehernand@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">
<div>Yes, its a little confusing.</div>
<div><br>
</div>
<div>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.</div>
<div>
<div class="m_1001546689258592143m_-1247458806721969361m_-6495079909516999116h5"><br>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Tue, Jul 4,
2017 at 12:24 PM, Josejulio Martinez
Magana <span dir="ltr"><<a href="mailto:jmartine@redhat.com" target="_blank">jmartine@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">
<div>I didn't know alerts included
metrics (I knew that metrics
included alerts)</div>
If they include each other, why
not call them as a whole instead
as the parts?
<div><br>
</div>
<div>Is confusing for me that they
are two distributions and that
each that are mutually included
in each other. What's the
difference?</div>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">
<div>
<div class="m_1001546689258592143m_-1247458806721969361m_-6495079909516999116m_7829651153661384658h5">On
Tue, Jul 4, 2017 at 12:04
PM, Edgar Hernandez Garcia <span dir="ltr"><<a href="mailto:ehernand@redhat.com" target="_blank">ehernand@redhat.com</a>></span>
wrote:<br>
</div>
</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div>
<div class="m_1001546689258592143m_-1247458806721969361m_-6495079909516999116m_7829651153661384658h5">
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<div class="gmail_quote"><span>On
Tue, Jul 4, 2017
at 11:55 AM, Edgar
Hernández <span dir="ltr"><<a href="mailto:ehernand@redhat.com" target="_blank">ehernand@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div text="#000000" bgcolor="#FFFFFF"><span> <br>
<div class="m_1001546689258592143m_-1247458806721969361m_-6495079909516999116m_7829651153661384658m_-3328935601235360523m_8533691624746647698m_1549882951652926925moz-cite-prefix"> And,
now, starting
with "<a href="https://github.com/hawkular/hawkular-metrics/releases/tag/0.27.0" target="_blank">metrics 0.27.0</a>" I can see
that metrics
also includes
alerts. </div>
</span><span class="m_1001546689258592143m_-1247458806721969361m_-6495079909516999116m_7829651153661384658m_-3328935601235360523m_8533691624746647698HOEnZb"><font color="#888888"><br>
</font></span></div>
</blockquote>
<div><br>
</div>
</span>
<div>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. </div>
</div>
<br>
</div>
</div>
<br>
</div>
</div>
<span>______________________________<wbr>_________________<br>
hawkular-dev mailing list<br>
<a href="mailto:hawkular-dev@lists.jboss.org" target="_blank">hawkular-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailma<wbr>n/listinfo/hawkular-dev</a><br>
<br>
</span></blockquote>
</div>
<br>
</div>
<br>
______________________________<wbr>_________________<br>
hawkular-dev mailing list<br>
<a href="mailto:hawkular-dev@lists.jboss.org" target="_blank">hawkular-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailma<wbr>n/listinfo/hawkular-dev</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div>
<br>
______________________________<wbr>_________________<br>
hawkular-dev mailing list<br>
<a href="mailto:hawkular-dev@lists.jboss.org" target="_blank">hawkular-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailma<wbr>n/listinfo/hawkular-dev</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div>
<br>
______________________________<wbr>_________________<br>
hawkular-dev mailing list<br>
<a href="mailto:hawkular-dev@lists.jboss.org" target="_blank">hawkular-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailma<wbr>n/listinfo/hawkular-dev</a><br>
<br>
</blockquote>
</div>
<br>
</div>
<br>
<fieldset class="m_1001546689258592143m_-1247458806721969361mimeAttachmentHeader"></fieldset>
<br>
<pre>______________________________<wbr>_________________
hawkular-dev mailing list
<a class="m_1001546689258592143m_-1247458806721969361moz-txt-link-abbreviated" href="mailto:hawkular-dev@lists.jboss.org" target="_blank">hawkular-dev@lists.jboss.org</a>
<a class="m_1001546689258592143m_-1247458806721969361moz-txt-link-freetext" href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" target="_blank">https://lists.jboss.org/mailma<wbr>n/listinfo/hawkular-dev</a>
</pre>
</blockquote>
<br>
</div></div></div>
<br>______________________________<wbr>_________________<br>
hawkular-dev mailing list<br>
<a href="mailto:hawkular-dev@lists.jboss.org" target="_blank">hawkular-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailma<wbr>n/listinfo/hawkular-dev</a><br>
<br></blockquote></div><br></div></div></div>
<br>______________________________<wbr>_________________<br>
hawkular-dev mailing list<br>
<a href="mailto:hawkular-dev@lists.jboss.org">hawkular-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/hawkular-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/<wbr>mailman/listinfo/hawkular-dev</a><br>
<br></blockquote></div><br></div>