Available translations
loading results
How to Contribute Tutorials
Summary: Tutorials are the ultimate educational resource available in Superalgos, and they play a crucial role during the onboarding of new users. Contributing tutorials is a great way to help the project grow the user base and is highly appreciated!
This page discusses best practices to build and contribute Superalgos tutorials. It doesn't cover the actual mechanics of building tutorials. Instead, it focuses on what is desirable.
Foundations->Concept->Reusable Documenting Snippets->The Quest for Quality
The Quest for Quality
At Superalgos, we take pride in the quality of the product we are building. Documentation and tutorials are crucial parts of Superalgos.
That said, we understand that it takes time and effort to get to a quality product, thus iterating on early prototypes and implementing early-stage feedback is a good way to achieve the desired quality standards.
Tip: When you write documentation or build a tutorial for Superalgos, you become the maintainer of what you've created. It is your responsibility to keep the material up to date with the system, and to implement the feedback users may share! Your material must become the ultimate resource to learn the topics it covers.
The Associated Workspace
To deliver the best possible experience, a tutorial must be featured in a specific Workspace, and the workspace must be custom-tailored to serve the tutorial. The workspace must be clean and feature the assets required for the learning experience to be optimal. It is best to keep the workspace clean, light, and stripped of unnecessary resources.
Use the USDT/BTC Market in Binance.com
If your tutorial deals with data, it is best to use the same exchange, market, and date ranges already in use in the Getting Started Native Workspace tutorials. This way, users will already have the data and can go through the tutorial easier.
Note: If for whatever reason the tutorial must deal with other markets and/or exchanges to deliver the content, then go ahead and ignore the above.
Tip: Make sure you include a step allowing users to switch to BinanceUS, in case they need to, just like in the Welcome to Superalgos Tutorial.
Tutorial Series & Planning
Some topics are broad, have ramifications, or require a nuanced analysis to be covered thoroughly. In such cases, planning for a series of tutorials is ideal.
Take, for example, the series of tutorials in the Trading System Design Tutorials Native Workspace:
- The first tutorial in the series gives a broad introduction to the topic, mostly in conceptual terms. This allows users to see the big picture and learn how the concepts are structured and why they are structured the way they are.
- The second tutorial in the series proposes an exercise that takes several more tutorials to develop and implement. That is, the tutorial sets the basis for what the series will cover.
- The remaining tutorials in the series dissect the exercise proposed earlier and cover with a fine level of detail the implementation. At the same time, they cover all the context and many lateral topics.
Note: The whole series threads a common theme and develops it from the simplest to the most complex concepts, step by step. A tutorial series must be exhaustive and eventually, cover the whole topic. It must become the ultimate tool to learn about the subject matter!
Tip: Consult with project maintainers what would be good names for each tutorial in the series. Naming tutorials with clear and descriptive names is important.
The Target Audience
People are different. We all have slightly different wirings in our heads, and we all learn differently. In that sense, building tutorials is a bit of a challenge. Some people like tutorials that go straight to the point and show them how to solve a very specific issue. Others prefer tutorials that get to the bone, explain every detail, and properly cover the context.
At this early stage, we can't afford to duplicate efforts and build different tutorials for different kinds of learners. We have to choose the method that best serves the project.
Important: We choose to focus on building comprehensive tutorials that everyone can follow and that leave no one behind. We believe that a tutorial that goes slow, covering every detail, and taking the time to explain the nuance is the right approach at this stage. By building tutorials in a such manner, we guarantee that those who are willing to invest the time to learn the system have adequate material to quickly become power users.
Such tutorials may be slightly annoying to fast-learners, or to people that just want a specific question answered. But such needs are already covered by the searchable knowledge base comprised in the Docs.
Communication Resources
Let's get into some of the specifics on building tutorials for Superalgos!
Superalgos tutorials have evolved through several months worth of feedback from early adopters. We feel we have found a sweet spot, and have started to develop a style in the way we use the space available in each tutorial step. The following are some notes that will help you build tutorials that match the format of existing tutorials.
Foundations->Concept->Reusable Documenting Snippets->Use Precise Language
Use Precise Language
The ultimate goal of documentation and tutorials is to provide users with a hands-on learning experience covering topics in detail. In general terms, we know the material is good — or has reached a mature state — when users ask no questions about it in the Support Group.
Be precise and unequivocal with language. Read your writing over and over in search of phrases that may not be easily understood, or that may be interpreted in different ways. Improve the sentences to make them as clear as possible. Remember, the less clear your writing is, the more questions we have in the Support Group.
Tip: Be prepared to iterate over and over until the material stabilizes. That will happen when there are no more questions about the topic in the Support Group!
Consistent Use of Space and Styles
Use the different sections on the page and the different paragraph styles for consistent purposes. This helps users get accustomed to a certain format so that they know what to expect from each section of the page. Consistency in the way the information is delivered makes tutorials more usable!
The Definition Box
The definition box is the space to the right of the icon, below the title. Use this space to introduce what the step is about, that is, to set up the story the step will tell, or to provide some basic context.
Note: To use the definition box correctly, explain the context in four to five lines. Avoid one or two lines or anything over five.
The Call For Action
The most important section on any given step is the call for action, that is, the instruction that the user must follow to progress in the tutorial. Many times users redo tutorials or go back a few steps just to make sure they did everything right.
Always use the callout style — the one applied to this paragraph — for the call for action! Similarly, try to avoid using this style for anything else. If the particular step doesn't have a call for action, then the step should not feature this style at all!
Each tutorial step should have a single call for action, that is, a single instruction that the user must carry out. This is the ideal case scenario. There may be exceptions, for example, when we ask the user to read a page in the Docs and do something else as the main instruction.
Tip: In general terms and when possible, try to avoid giving the user more than one task on the same step. Instead, if you expect the user to perform several sequential actions, try to split the process into more than one step — as many as it takes.
In some cases, you may need the user to take a very simple action so that the main call for action may be delivered. In such cases, you may use the definition box to tell the user how to get ready to execute the call for action delivered later in the page.
Foundations->Concept->Reusable Documenting Snippets->Alternating Colors
Alternating Colors
Colorful pages look great, while white pages full of text are harder to follow. Make sure you break the monotony with the four different styles of boxes:
Tip: This is great for additional tips.
Note: Use this every once in a while to break up otherwise large sections of plain text.
Important: Leave this box for the truly important stuff. Things you don't want users to overlook or forget.
Warning: And this one, save it for real warnings. Things that may represent a threat or risk.
Use of Docs Pages
When you need the user to learn about a specific concept to get the proper context on the subject, do not replicate in the tutorial information that exists in the Docs. Duplicating information is not a good idea, as it makes it harder to maintain the Docs and tutorials.
Tip: Asking the user to read a page or a section of a page in the Docs is the correct approach. This has the added benefit of making the user aware that the Docs cover the topic too.
Important: If you find that the relevant page in the Docs is outdated, doesn't cover the topic with the appropriate depth, or maybe even doesn't exist, helping create, complete, and/or improve the delivery of the information in the Docs is just as valuable as building the tutorial! Long format explanations do not fit well in tutorials. They do fit well in the Docs!
Interactivity
The whole point of tutorials — and the main difference with the Docs as learning material — is that they offer the opportunity for hands-on learning. Tutorials are interactive while the Docs are less so!
Make sure you use this quality to the fullest, but also try to maintain a certain balance!
- If the tutorial is talking about a hierarchy, a group of nodes, or a particular node, make sure that the tutorial step takes you to that place in the Workspace. This adds a visual element to the explanation and helps the user get familiar with the data structures involved.
- Tutorials can affect the Workspace in many ways replicating actions the user may do. When you want the user to learn to do something, it's best to ask the user to do it, instead of having the tutorial do it for the user.
- On the other hand, the tutorial should take care of doing certain things that are not conducive to learning something relevant to the context of the tutorial. Performing these actions directly may help keep the user focused on what matters most.
- In some cases, the actions users take may have certain effects. Showing users the outcome of their actions immediately after completing a task has a great educational value. For example, if the user is setting up a new Time Machine in a tutorial about the Charting Space, show users how the time machine appears in the charting space immediately after creating it. If users then set up a Timeline Chart that references a particular Data Mine, show users how the new Timeline Chart appears within the Time Machine, and let them verify that the expected layer managers are there. Don't be afraid to go back and forth... that is the whole point after all!
Foundations->Concept->Reusable Documenting Snippets->Tooltips
Tooltips
The system recognizes the name of all entities that have a Docs Page when the name of the entity is written in title case. When that happens, the system automatically creates a tooltip for the phrase. This is a valuable resource, as it provides context that you don't need to explain.
Make sure you use this resource wisely, as too many tooltips on a single page may be overwhelming, and probably irrelevant.
Tip: When you believe the tooltip is relevant, then write the name of the entity in title case. If the tooltip is not relevant, then write the name of the entity in lower case.
Naming of Nodes
Superalgos is a complex system. Helping users develop good organizational habits is highly desirable. The more top-level users we may help form, the more powerful the project becomes.
When users create new data structures, it's good practice to have them name the relevant nodes. This is particularly important with nodes that pass on their names through references to other nodes.
Note: Make sure your tutorial goes the extra mile and reminds users to name those kinds of nodes. Proposing a specific name is ideal. Remember that the user may not know what comes next or what the node is used for at the time of creation, so they may not know what a relevant name may be. But you do, so you may propose a name that is consistent with the tutorial's goal.
Look & Feel
There is a philosophical debate on whether beauty is objective or subjective. Some people think beauty is in the eyes of the beholder, while others believe that there are inherently beautiful things.
Whatever the case may be, we want the overall look & feel of tutorials to be consistent!
Here's a list of requirements that help tutorials be consistent in their look & feel:
- Always use an icon to illustrate the step. Sometimes the appropriate icon is the one corresponding to the node the user is working with. Other times you may use icons figuratively, playing with alternate meanings of what the drawing may represent.
- Avoid stud step pages. Steps with very little content seem empty and feel strange. You don't need to feel the space with gibberish or unnecessary information. Instead, try to use the space to provide context for the call for action. Explain why the user is asked to do this or that. Let the user know what may be expected from the action and so on.
- As a corollary of the above, the opposite case may be problematic too. That is, when the content barely fits the page and gets too close to the row of buttons fixed at the bottom of each step. The problem is that some browsers / OS combinations render styles slightly differently, and what may seem close to the buttons in one system may overlap the buttons in the next. Try to level at least one full empty line — preferably two.
- Do not set two consecutive paragraphs with the same style. The only exception is for bullet lists. Even the Docs Text Style is not formated to look good as consecutive paragraphs in the context of a tutorial (there is no padding between paragraphs).
- Leave at least one line empty before the buttons at the bottom of the tutorial window. Otherwise, in other browsers, the content may overflow the window.
Foundations->Concept->Reusable Documenting Snippets->Title Case
Title Case
Always use proper title case for titles. But, what exactly is proper title case? Let's agree to the standard proposed on this blog post:
Tip: Titles look best when they span a single line. Use two-line titles only if strictly necessary!
Unique Identifiers
Unique Identifiers
Important: Remember that the title of a tutorial step is also the unique identifier of the corresponding Docs Page. This means that the system does not allow for duplicate titles. Avoid at all costs naming pages after single words or short phrases. Let's leave those unique names for particular cases that may merit the use of such special phrases.
For the same reason, all titles should begin with the following fixed string of text:
Tutorial Step - The above helps reserve some phrases for contexts different than tutorials.
Tip: Don't worry! Your titles will not look ugly in the tutorial, as the system filters the prefix and doesn't show it in the tutorial window!
Foundations->Concept->Reusable Documenting Snippets->Proper English
Proper English
There are at least two reasons why it's desirable to have spell and grammar-checked content:
- Proper language speaks to the quality of the product.
- Users who don't speak English may be using online translators, which perform well only when they have a proper source.
Important: Always use a grammar and spell-checker to make sure your content is as correct as it may be!
The First Page
The very first page of a tutorial is a page that briefly describes what the tutorial is about, using the Summary field. The page must have the same name as the tutorial and end with the word `Tutorial`, as the summary you enter will serve as a tooltip when the tutorial is mentioned across the Docs.
For example, the first page of the Welcome to Superalgos! tutorial is Welcome to Superalgos Tutorial.
Tip: See the Welcome to Superalgos Tutorial page for an example.
The First Few Steps
- Tutorials should start with a welcome message, and a clear explanation of what the tutorial is about, including a brief description of what the user will do while following the tutorial, and what lessons will be learned. No need to compress everything into a single step... two and even three steps are fine.
- If the tutorial requires prior knowledge beyond the Getting Started Tutorials Native Workspace, devote a step to explaining what prior knowledge is required so that users may complete the relevant tutorials first.
- You should also take the time to explain what's featured in the Workspace. The idea is that users should get familiar with the workspace as soon as possible, to understand how it may differ from other workspaces they may have encountered earlier. You can mention which mines you will use, clarify if they are added as plugins or not, which trading systems, and so on. You may skip the mandatory hierarchies, like Network or Trading Engine.
- If you installed any markets, created custom charts, a particular setup of tasks in the Network hierarchy, or any specific data structure that is not present in the default market installation, make sure you explain what you did and why. It may be confusing for users to find things and not know how they got there.
The Last Few Steps
- If there are more tutorials in the series, make sure you leave users right by the next one, inviting them to keep going.
- If the remaining tutorials in the series are not ready yet, then use the last few steps to describe what else will be covered in the series and ask users to stay tuned.
Wrapping Up
When your tutorial is ready and has been reviewed by project maintainers, there a few things you need to take care of so that the workspace and tutorials are easily findable.
Create a Page for the Workspace
Every workspace must be documented, so make sure you create a page for the workspace in the `Community Workspaces` Topic.
Important: Please use a clear and descriptive name and follow the naming convention ending the name with `Native Workspace`. Feel free to consult what a good name may be with other contributors in the Docs Group.
List of Native Workspaces and Tutorials
Add the workspace and the tutorial to this list: List of Native Workspaces and Tutorials, so that they show up in the First Steps Tutorials book.
Tip: Consult with project mantainers the spot the tutorial should take in the list.
First Step Tutorials Book
Add the tutorial as a chapter in the First Steps Tutorials book.
Contributing to Superalgos — TOC
You just read page 6 in the topic.
1. How to Contribute to Superalgos
2. How to Contribute a Trading System
4. How to Contribute to the Docs
5. How to Contribute Translations