example-guide.adoc

Use this new feature

Tip

About writing a guide A guide is a document offering step by step instruction to reach some goal. Guides are technical in nature and tend to make assumptions about the consumer’s environment. To help create guides that will work in most environments, please follow these ideas. Keep links to a minimum - when someone is learning a new concept for the first time and every other word is linked it makes things confusing and hard to get a good flow going. Instead, annotate a word or phrase and provide a "Resources" area at the bottom of the guide. Separate products and runtimes in tabs - it is common to reach the same result through multiple ways. An example is creating a tenant/namespace/topic in Astra Streaming and Luna Streaming. Both have the same result but get there in very different ways. Offer each as a tab and let the consumer choose their path. The step after the tabbed step can assume the consumer has complete the previious step and is in a known state. Runtimes follow the same pattern. Weather one is using Java or C#, they are still creating a {pulsar-short} client to interact with the cluster. Create a single step in the guide with multiple tabs for each runtime. Be thoughtful about the names you use - if you are leaning a new concept or feature with no background on the product, words matter. Labeling a tab as "Luna Helm" and then referring to it as "{pulsar-short} Helm Chart" are two distinct things to that reader. The author of the document has such deep understanding that they consider those things the same - and technically they are at {company}. But the read isn’t from {company}, so be mindful of their context. Talk in first person - humans create the guides and humans consume the guides. Write as if you are paired with your consumer in doing what ever the guide does. Use "we", "us", "you".

Have you ever wanted to use this new feature? Well look no further than this guide to get started. We will be implementing it from scratch and you will find a set of links at the bottom to continue use of the feature.

Pre-req’s

You will need the following things in place to complete this guide:

• about 5 minutes

• a working {pulsar-short} topic (get started here if you don’t have one)

First group of tasks

This is the first group of tasks[1] that need to be complete before moving on to the next group. Each group provides simple starting/stopping points for the consumer as well as a good summary of whats needed to create the new feature.

1. Do this

2. Then this

   1. You’ll need to do this during this step

   2. And also this

3. Then this after that

Second group of tasks

This is the next group of tasks[2]. You get the point of task groupings.

1. This step can be done in different runtimes and uses tabs

C#

var a = new Something();
Console.Write(a.thing);

Java

class aa{
  public aa(){}
  public String doSomething(){
    return "a string";
  }
}

Summary

In this guide we created a new feature and did the basics of interacting. Now it’s time to extend the feature and become a ninja!

Resources

Some resource talked about in the guide

Another resource talked about in the guide

Next steps

Here are links to other guides you might be interested in:

• Something

• Something else