What are learn guides
Our collection of guides are simply a collection of articles and tutorials that aim to help members of the Civo community use the platform more easily. We have guides describing how to use particular Civo features, documentation on how to complete tricky processes with Civo, and others still providing helpful information on cloud-native, Kubernetes, or commonly-faced issues in general.
We welcome submissions from the Civo community! Any knowledge or experience that isn’t already covered (and that you think might be helpful to others) would make a great topic for a learn guide. This document walks you through the process of submitting a guide or tutorial article on the Civo platform.
Learn guides submitted by our members will be reviewed by our administrators and, subject to any changes we feel appropriate to enhance clarity, published on our site. We'll use your name, your Twitter username and GitHub profile (if you've set them in your profile) to give you credit, and share all published guides to our social media and community feeds.
How to create a learn guide
Click 'Create Guide' under the Content section of the sidebar
This resulting page displays a private list of your own learn guides. Feel free to create and delete as many guides here as you like. Guides created here will remain private and visible only to you until submitted for publishing. If you wish to build up your own library of helpful guides for your own private use, you can keep guides private rather than publish them.
Click 'Create Guide' at the top of the page
The resulting form is where you enter the content of you learn guide. It has a number of fields aside from the title and the article body:
The 'snippet' will not appear in the guide itself, but is a short description of the guide provided to users on certain pages and on social media links. The snippet is the text under the title in the image here, for example:
The image for social media is optional, but recommended. You will also be able to upload an image that will appear on social media cards when the guide is shared. Choose a screenshot or something that will best illustrate the purpose of the guide.
The main body of the guide is formatted in Markdown.
Guidance for guide content
We suggest breaking your content up with ## subheadings to make it more readable. There are no rules to the section headings, but it's usually good practice to have a general introduction to what the guide aims to teach a reader, followed by section(s) for implementation, and a wrap-up at the end.
When you consider the title, think of what would make you want to read it. Include all the relevant keywords to attract a reader's attention.
We recommend you include screenshots or images that visually show a reader what is happening. When the guide is published, images are transferred over to be hosted by our system to save on bandwidth.
Please make sure to ensure all content is your own, or attributed to the original source. Please do not copy and paste content from elsewhere without proper attribution.
Once your guide is written, we recommend you run it through a spelling and grammar checker to root out any pesky typographical errors. Many IDEs that handle Markdown have spelling highlighting plugins that you can use.
Complete content and click 'Save'
Your draft learn guide has been saved but remains private. You may continue to make changes to this guide by clicking the 'edit' button, or view how the guide will look once published by clicking 'view'.
Click 'Submit for publishing'
Once submitted, the guide will be made available for review by Civo's administrators. Any significant changes required will be communicated to you, and we will work together to get the best version of the guide out. We reserve the right to change the guide before publication as an official guide. Please be aware that you give us a irrevocable licence to use the content, amending it as we see fit (for example, for breaking version changes). We will of course always give you credit for the guide you wrote..
Once we're happy with how the guide reads, a Civo administrator will publish the learn guide for general consumption. The final published version remains separate from the version saved in your own learn guide list, and it's important to note that even if you delete your own version, the published version will remain.
Can I update my learn guide after it is published?
Of course. We recognise that things change and updates my be required. Even after publishing you can continue to edit your guide in the normal way, but you will need to resubmit the guide for publishing.
You can always contact us either via support or in the Civo community Slack for advice. We want to work with you to get your work showcased!
