Style Guide
Content Categories
Solutions
Solutions are open source code samples of applications accompanied by technical explanations. We use the definition of “application” here broadly to mean a use case-based application (e.g. a proof-of-concept for a point-of-sale application) or an interesting or creative code-based approach to solving a problem with Algorand that other developers may find useful (e.g. Using AWS lambda for sending TEAL transactions, React Component for Asset Creation on Algorand).
Solutions are intended for developers who want to browse examples of what is possible using Algorand’s blockchain technology and be able to reference code to get started on their own applications. As such, we welcome both types of solutions and encourage a diversity of subject matter (finance, supply chain, infrastructure, statistics, security, frameworks, etc.).
See the Solutions Hub for published examples.
Requirements
A Solution includes:
- Code Sample (required) - The code for your solution in a public Github repository with an open source license.
- Write-Up (required) - A full technical write-up describing your solution, why it matters, and any other relevant information for developers. This is written in markdown. Read more about the format of this write-up below.
- Title (required) - Make this clear and concise.
- Short Summary (required) - 1-2 sentence summary of the Solution to be displayed on the Solution card view.
- A Featured Image (required) - To be displayed on the Solution card view and on the detail page view. Please reach out to your Algorand contact if you need support generating an image.
- Video (optional but encouraged) - A video demonstrating your solution for developers.
- Images/Charts (optional but encouraged) - Any supplementary images to be referenced within your write-up.
Format of the Write-Up
The write-up begins with an overview, which is a 1-2 paragraph summary of what the Solution is. You should briefly state which technology it uses and who/what it is intended for. We also strongly encourage that you include a conclusion at the end. It is up to you how you want to present and structure the rest of the write-up. Remember that your readers are developers so your writing should be technical and can include code snippets and diagrams where relevant.
The entire write up must be written in markdown, which will be rendered to match the overall theme of the Dev Portal once published. See the full list of available rendering options for your document in the Formatting Reference.
There are a few structural components you must include at the beginning and end of the write up. They are the overview text (mentioned above), a [TOC] tag that autogenerates the table of contents based on the headers in your write-up, and a conclusion section. See the template below.
Template
This is your Overview paragraphs section. There is no header required here as this will be added automatically on publishing. We encourage two paragraphs summarizing the Solution, the technology used, who this is intended for, and why it matters.
[TOC]
This is where you should put the body of your content. Use markdown headers and formatting features to structure your content.
# Example Conclusion Header
This is your concluding section. You can call it whatever you want, but make sure to wrap things up and maybe include some inspiration for next steps if relevant.
Tutorials
Tutorials are step-by-step guides that help developers complete specific functions on the Algorand blockchain.
Choose a Tutorial Goal
Before beginning a tutorial, determine what you want the user to accomplish by the end of it. Tutorials are best when they are simple (not too many steps), modular and composable. In many cases, it is better to have the user focus on a single goal and reference other tutorials as needed for prerequisite knowledge. As an example, if I want to create a tutorial that shows how to reconfigure the manager address for an asset using the Python SDK, I could create or reference a separate tutorial that teaches users how to create an asset. That way the user can choose to do that tutorial first or they may feel that they already have enough prerequisite knowledge and can jump straight into the tutorial that just talks about reconfiguring the asset.
See the Tutorials Hub for published examples of Tutorials.
Requirements
- Title (required) - This should be short and concise but descriptive enough so that users will know enough about what they will accomplish without the need to open the tutorial.
- Short Summary (required) - 1-2 sentences about what the user will accomplish. This will be displayed in the card view of the tutorial and for search engines.
- Long Summary (required) - A 2-4 sentence summary of what the user will accomplish in this tutorial and why it is important. This will be displayed at the top of the tutorial.
- Requirements (required) - A list of all the prerequisite tools or knowledge the reader must have in order to complete the tutorial.
- Background (optional, but encouraged) - Extra relevant background knowledge on the subject that is not required but may be helpful to the reader. This is concise free form text with inline links. Link to the Algorand docs for detailed explanations of topics.
- Main Language (required) - The primary programming language or tool the user needs to use to complete this tutorial.
- Additional Languages (optional) - The exception to only having one language is when the specific tutorial requires certain steps be done with a different tool . For example, an advanced tutorial may describe a process to create a contract (in TEAL) but to build an application around it in Javascript. In this case, the main language would be JavaScript and the additional language would be TEAL.
- Level - Choose Beginner, Intermediate, or Advanced. See level descriptions below.
- Time to Complete - This is the amount of time it will take the user to complete the tutorial from Step 1 through the final Step. The time to complete does not include any prerequisite steps. Choose from: 15 minutes or less, 30 minutes, 1 hour, or 1 hour +.
- Steps - Numbered step titles to complete the tutorial. Keep these concise but informative.
- Body Content - Written in markdown and accompanies each step. See the Formatting Reference to learn which markdown features are available and how they will render.
- A Featured Image (required) - To be displayed on the Tutorial card in the Dev Portal. Please reach out to your Algorand contact if you need support generating an image.
- Video (optional but encouraged) - A video that walks through through each step of the Tutorial for developers.
- Images/Charts (optional but encouraged) - Any supplementary images, which can be inserted within any step body content.
Level Descriptions
- Beginner - Little to no prerequisite knowledge required to complete this tutorial besides some familiarity with the language the tutorial is written in. Beginner tutorials should be easy for any developer. Examples: Create an account on TestNet with Python - Send 10 Algos on TestNet - Create a JavaScript Webapp that displays the latest block on MainNet .
- Intermediate - Some prerequisite knowledge required to complete this tutorial and/or the complexity of the subject requires some level of familiarity that would be difficult for someone who is just getting started.
- Advanced - These tutorials assume that the developer has significant prerequisite knowledge in the subject (that may not always be explicitly named) and/or the concept of the tutorial is complex, integrating a number of concepts, frameworks, platforms, etc.
Articles
Articles are technical Algorand-focused blog-like posts for developers. These are entirely free-form depending on the subject matter. The Algorand Foundation is currently not offering any rewards for Article submissions.
Formatting Reference
We leverage the Material for Mkdocs package with several extensions activated. All of the basic markdown functions are available, such as bulleted lists, numbered lists, headers, etc. The list is non-exhaustive but includes the most relevant rendering functions. Please let us know if something is missing that would be helpful.
Headers
We support nested headers.
# Header 1
## Header 2
### Header 3
#### Header 4
...
Table of Contents
Automatically generate a table of contents based on the headers of the page.
Markdown
[TOC]
Result
See the table of contents at the top of this page.
Links
Use relative links if referring to anything on this website and use absolute links for anything external.
Markdown
[Link to Documentation Home](../../docs)
[Link to Tutorials Hub](../../tutorials)
[Link to Solutions Hub](../../solutions)
[Link to Create a Private Network Tutorial](../../tutorials/create-private-network/)
[Link to Step 5 in Private Network Tutorial](../../tutorials/create-private-network/#step-5)
[Link to Creating an Asset Section on the Assets Documentation Page](../../docs/features/asa/#creating-an-asset)
[Link to Specific Section in a Solution](../../solutions/decentralized-two-factor-authentication-algorand-standard-assets/#the-client)
[Link to algorand.com](https://www.algorand.com/)
Result
Link to Documentation Home
Link to Tutorials Hub
Link to Solutions Hub
Link to Create a Private Network Tutorial
Link to Step 5 in Private Network Tutorial
Link to Creating an Asset Section on the Assets Documentation Page
Link to Specific Section in a Solution
Link to algorand.com
Images
Image links are auto-generated after they are uploaded from within the dev portal. They can be referenced as follows:
Markdown
Result
Videos
Embed videos using the following code:
<iframe width="560" height="315" src="https://youtube.com/embed/{your-video-id}" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
Tables
Alignment
In most cases, you should not need to align content. The exception to this is for images that are less than the full width of the screen and look odd if not centered. In this case you can do the following.
Markdown
<center>
</center>
Result
Info/Warnings/Tips/Notes
You can add call-out bars for specific things as described here.
For example, to add a Tip.
Markdown
!!! tip
Make specific callouts using this formatting option.
Result
Tip
Make specific callouts using this formatting option.