[Hawkular-dev] hawkular.org - Redux Initiative

Julie Stickler jstickle at redhat.com
Wed Jul 5 16:29:18 EDT 2017 

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.io%2F>]
   site is very clear right away.
   -

   Project Calico [https://www.projectcalico.org/
   <https://mojo.redhat.com/external-link.jspa?url=https%3A%2F%2Fwww.projectcalico.org%2F>]
   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.org%2F>]
   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.openshift.org%2F>]
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.com%2Fdocs%2F>]
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.com%2F>]
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 at redhat.com    T: 1(978)-399-0463-(812-0463)     IRC: jstickler

On Wed, Jul 5, 2017 at 10:39 AM, Jay Shaughnessy <jshaughn at redhat.com>
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 at 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 at 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 at 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 at redhat.com> wrote:
>>>>
>>>>>
>>>>>
>>>>> On Tue, Jul 4, 2017 at 11:55 AM, Edgar Hernández <ehernand at 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 at lists.jboss.org
>>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> hawkular-dev mailing list
>>>> hawkular-dev at lists.jboss.org
>>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>>
>>>>
>>>
>>> _______________________________________________
>>> hawkular-dev mailing list
>>> hawkular-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>>
>>>
>>
>> _______________________________________________
>> hawkular-dev mailing list
>> hawkular-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>>
>>
>
>
> _______________________________________________
> hawkular-dev mailing listhawkular-dev at lists.jboss.orghttps://lists.jboss.org/mailman/listinfo/hawkular-dev
>
>
>
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hawkular-dev/attachments/20170705/d14c6a95/attachment-0001.html

More information about the hawkular-dev mailing list