Re: [Hawkular-dev] hawkular.org - Redux Initiative

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-document... 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: