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?***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:
Exploration
Getting Started
Onboarding/Problem Solving
Guidance and Discovery
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/] site is very clear right away.
Project Calico [https://www.projectcalico.
org/ ] takes one line to explain what their purpose is right at the top of the pageKotlin [https://kotlinlang.org/] 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/]. 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/] 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/]. 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/] 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/] where they let people publish their own creations. This makes the community feel more passionate.
JULIE STICKLER
TECHNICAL WRITER
Westford – 3S353
jstickle@redhat.com T: 1(978)-399-0463-(812-
0463) IRC: jsticklerOn Wed, Jul 5, 2017 at 10:39 AM, Jay Shaughnessy <jshaughn@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@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@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@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@redhat.com> wrote:
______________________________
On Tue, Jul 4, 2017 at 11:55 AM, Edgar Hernández <ehernand@redhat.com> wrote:
And, now, starting with "metrics 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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
_______________________________________________
hawkular-dev mailing list
hawkular-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
_______________________________________________
hawkular-dev mailing list
hawkular-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
_______________________________________________
hawkular-dev mailing list
hawkular-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
_______________________________________________ hawkular-dev mailing list hawkular-dev@lists.jboss.org https://lists.jboss.org/mailma n/listinfo/hawkular-dev
_______________________________________________
hawkular-dev mailing list
hawkular-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev
_______________________________________________
hawkular-dev mailing list
hawkular-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev