Hiya. Welcome to the Astra getting started guide template. Use this template to help "guide" you through authoring "getting started" guides within DataStax Astra. 😏
"Getting Started" guides are a unique way to help Astra users learn about a topic or how to perform a set of actions. The goal is to make it dead simple for a user to run through a guide and achieve some goal.
It is assumed that if you are following this template that you intend to write a guide for DataStax Astra. With that, we highly encourage you to download this markdown file and view it in both edit and rendered modes so you can easily see hidden comments.
If you'd like to see a working example of this guide navigate here and login to Astra.
In this guide, we will discuss
- Creating your guide in Github
- How to format guides and create actions
- Configuring your guide
- What not to do 😬
- How to submit a guide
If you don't have any prerequisite content just remove this section altogether.
This section contains items that a user may need from outside of Astra. Examples are things like Maven for Java or installing Node or Python.
- If any prereqs are required be explicit and call them out
- Provide links to needed resources
- Here is an example:
Here's something for fun
Try to make this short and descriptive.
Use camelCase, meaning capitalize the first letter of each new word after the first word.
This will be the path used in Astra to access your guide.
Here are some examples:
- introToDataWithAstra
- overviewOfAstraDB
- astraDBApplicationQuickstartPython
Now that you have a directory name you can create it along with your README.md in Github.
To do this, click the Add file drop down in the top right hand corner and choose the Create new file option within this repo. This will bring you to a page like you see in the image below.
Here, you will both name your guide directory and create a README.md file to work from.
Start off by typing the name of the directory for your guide in the field provided. Then, type a slash character "/" right after the directory name and add README.md.
So in the example above, we typed "yourDirectory/README.md" directly in the field provided.
If you already have some text for your README.md file can you paste it directly into the field provided.
Note the example "Put things here in the README.md file" in the image above.
Also, don't worry if you don't have all of your text ready, you can always edit more later.
Ok, now we're ready to create a branch.
To do this, scroll down to the bottom of the page from the previous step.
Click the Create a new branch and start a pull request radio button.
Fill out the branch name in the field provided. Github should automatically fill in your username. Just add your directory name and the word "guide" separated by dashses (for example: SonicDMG-yourDirectory-guide) as you see in the image below.
Then click Propose new file.
Now that you have a branch you should see a screen like the one below.
Click the ...pull request dropdown on the lower right hand corner.
Choose the Create draft pull request option. The button will change to Draft pull request.
Now click this button to create a draft pull request. A draft pull request means you are still making edits and it's not ready for review.
Finally, we need to get to your newly created README.md and open it for editing.
Look at the image below.
You should see a link to the branch you just created.
Click this link. This will bring you directly to your newly created branch within Github.
Now click on the new directory you added previously.
README.md should be selected by default. Click on the edit (pencil) icon on the top right to start editing.
Once you're done with your edits, scroll down to the bottom of the page and commit your changes to your branch.
Note: Once you have a draft PR in place you can continue to make changes as needed.
Follow the sections below to learn how to format your guide. Once complete, the last step (5) will explain how to submit your PR for final review.
Generally, formatting is pretty open and follows normal markdown styles. The main caveats being guide metadata in the overview, using numbered sections for proper styling within Astra, and using actions.
Glad you asked. Actions are special options that allow you to easily bring a user through a set of Astra specific operations with a simple button click. The goal is to remove friction from the user experience and make it easier for guide creators to add in more complex operations.
An example is database creation. If you want a user to create a database then use <<createDatabase>> directly in markdown. Again, use edit mode to see a real example.
<>
If you've done this correctly in markdown you'll only see the rendered action. Within an Astra guide this will translate into a fully operational button or link with status updates and other functionality.
Note: Actions will potentially bring users into a new flow to complete the action, but will then bring users back to the guide once exited.
<<createDatabase>>
<>
<<createVectorDatabase>>
<>
<<createToken>>
<>
<<launchCQLConsole>>
<>
<<downloadSCB>>
<>
<<launchDataLoader>>
<>
Ok, so now you've got the basics down and have some content. Great, before you submit, there's one more thing for you to do. You must configure your guide.
Each guide will have it's own section within the config.json. The metadata for THIS guide template looks like this.
"astraPortalGuideTemplate": {
"locale": "en-us",
"title": "Astra Portal Getting Started TEMPLATE 🎇",
"description": "Get an overview of how to write 'getting started' guides for DataStax Astra.",
"skillLevel": "Beginner",
"timeToComplete": "10 minutes",
"recommendedLinks": [{
"url": "https://www.freecodecamp.org/news/how-to-create-a-local-git-branch/",
"text": "How to create branches in Git"
}, {
"url": "https://github.com/markdown-templates/markdown-emojis",
"text": "All the markdown emojis"
}],
"recommendedGuides": [
"overviewOfAstraDB"
],
"contentSrc": "astraPortalGuideTemplate/README.md",
"stepCount": 6
}Again, just use this one as an example for your own guide.
Ok, let's break each property down to see what they do.
This one is important. Not only is it the unique name given to your guide, but it determines the route to the guide within Astra. Case matters!
"astraPortalGuideTemplate": {By setting this property the route in Astra will be "https://astra.datastax.com/guide/astraPortalGuideTemplate"
The guide detail section will give users high level information about your guide. Things like the title, a short description, skill level, and approx. time to complete.
The title should conform to 20 chars min, 73 chars max.
The description should conform to 40 chars min, 110 chars max.
"locale": "en-us", // just use this value for now
"title": "Astra Portal Getting Started TEMPLATE 🎇, but I need more to hit 73 chars🚀",
"description": "Get an overview of how to write 'getting started' guides for DataStax Astra and then keep going to 110 chars.🌈",
"skillLevel": "Beginner",
"timeToComplete": "10 minutes",Each of these values will then be automatically rendered within Astra, both in the title cards displayed on the home page and within the guides themselves.
While you may include inline links for content, guides also include explicit resource call outs in the right-hand side navigation. These are for links you really want to bring attention to and should be constrained to just a few links at most.
The example below contains two links that will be displayed under the auto-generated table of contents to the right.
"recommendedLinks": [{
"url": "https://www.freecodecamp.org/news/how-to-create-a-local-git-branch/",
"text": "How to create branches in Git"
}, {
"url": "https://github.com/markdown-templates/markdown-emojis",
"text": "All the markdown emojis"
}],If your guide is part of a larger set or you want to point users to a different guide upon completion of your guide use the "recommendedGuides" property to do this. Similar to recommended links you can provide multiple guides if you wise.
Values you use within the recommendGuides section MUST MATCH guide names from the config.json EXACTLY.
"recommendedGuides": [
"overviewOfAstraDB", "introToDataWithAstraDB"
],Finally, we come to the contentSrc and stepCount properties.
The contentSrc property tells the guide renderer where in the repository your guide exists. If this value is incorrect your guide will not render.
The stepCount property tells the renderer how many steps you have in your guide. For example, this guide has six steps ending with "6 How to submit a guide". So, the stepCount in this case should be "6". The renderer will do the rest and auto-generate the table of contents and all that.
"contentSrc": "astraPortalGuideTemplate/README.md",
"stepCount": 6
}We ask that you don't include artifacts that go stale, like UI screenshots that change over time. Our goal is to provide guides that are as maintenance free as possible for both you and our users. Nothing like using a guide that was great a year ago only to find out nothing in it works halfway through.
Ok great, your guide is ready and now you want to submit a pull request (PR) to get it published. All we need to do is mark your draft pull request "Ready for review" in the Pull requests tab in Github.
Click the Pull requests tab.
Click on your pull request.
Click the Ready for review button.
That's it! At this point one of the review team will be notified to start reviewing your request. Awesome job!