Getting Started guide

[Steve Krouse]

@Xkonti I'd like you to fill out these TODOs. Feel free to tweak this template as you go. It's just a rough skeleton.

The purpose of a getting started guide is: TODO

Here are some exemplars from devtools that developers love:

1. TODO
2. TODO
3. TODO

Here's what we should steal from each of them: TODO

Here's my suggested outline for the getting started guide: TODO

[Xkonti]

Introduction

The Getting Started Guide for Val Town should be designed to provide new users with an accessible introduction to the platform's most important capabilities. The goal is to give users a solid base in a single place - the basic skills that will allow them to go through the rest of the docs without much confusion or jumping around. Additionally it should ignite users' creativity and showcase the platform's potential for both simple and complex applications.

Content

• Familiarization - The content of the guide should ensure that the reader gradually gets more familiar with how the platform works and doesn't assume any topics as "already known". It's easier to skip over an explanation of something you know rather than being stuck and needing to do research.
• Ease of Use and Iterative Development: The guide should demonstrate how Val Town simplifies and accelerates the development process. It should illustrate the platform's user-friendly interface and tools that facilitate rapid testing and deployment. The emphasis will be on the iterative development approach, encouraging users to start with basic implementations and gradually evolve their projects, thereby enhancing their understanding and skills progressively.
• Usage of Various Val Types: Users should be introduced into some of the basic types of vals available in Val Town. It should explain the purpose and application of them. This knowledge is crucial for users to understand the versatility of Val Town and how to choose the right tools for their specific needs.
• Basic Built-in Storage: Users should be introduced to Val Town's simplest form of built-in storage - blob storage. The aim is demonstrate the ease of storing and retrieving data without the need for complex configuration. This will also serve as an ice breaker to introduce other types of storage available in Val Town as an idea of further development at the end of an article.
• Serving HTML: Explanation of how to create and serve static HTML content using Val Town. This should showcase Val Town's capability to host and display web pages, highlighting the simplicity of turning code into a live website. This should be kept to a simplest form possible as it's a rabbit hole.
• User Interactivity via API: Users should learn how to make their projects interactive by responding to API requests. It should cover the basics of setting up an API in Val Town, demonstrating how to process user input and respond to requests. This part is particularly important as it opens the door to a wide range of possibilities for user engagement and dynamic content creation in web applications.

Structure

1. Short Description of Val Town: Begin by introducing what Val Town is and its primary purposes. This section is crucial as it sets the stage for new users who might be encountering Val Town for the first time (after searching for "Val Town"). A succinct and clear explanation will help them understand the platform's unique features and its purpose.
2. Interface Overview: Provide a comprehensive overview of Val Town's user interface. Explain the layout, key components, and how to navigate the platform. This part is essential to familiarize users with the environment they will be working in, making subsequent steps more intuitive and accessible. This part of the Getting Started might serve as the "one and only" place where the interface is explained reducing the need for screenshots/explanations in the rest of the docs.
3. Project Overview: Present a concise overview of the project that will be developed throughout the guide. Outline its purpose and what the user will achieve by completing it. This gives users a clear idea of what they're building.
4. Step-by-Step Instructions: Break down the project into a series of manageable and sequential steps. Each step should include detailed instructions, code snippets, and explanations of how each part contributes to the overall project. This methodical approach ensures users can follow along and understand each aspect of the development process. Here is where the user has a chance to "learn by doing" where the guide focuses on one problem/feature at a time.
5. Summary and Expansion Ideas: Conclude with a summary of the project and the key concepts covered in the guide. Provide suggestions on how users can expand upon the project or apply the skills learned to other scenarios. This section is aimed at reinforcing the knowledge gained and inspiring users to explore more of what Val Town has to offer.

Each section is designed to build upon the previous, ensuring a smooth and logical flow through the guide. The goal is to provide users with a solid understanding of Val Town's basics and its capabilities, encouraging them to delve deeper into the platform's potential.

Limits

• Simplicity Over Complexity: Ensure the guide remains accessible to beginners by avoiding overly complex topics or in-depth explanations of advanced features.
• Focused Scope: Limit the guide to cover essential features and functionalities, avoiding the temptation to showcase every possible capability of Val Town.
• Practical Application: Choose a project that is simple yet practical, allowing users to see immediate results without overwhelming them with lengthy code examples.

Inspiration

Examples of great "Getting Started" guides:

• Plaid Quickstart - A getting started tutorial for Plaid. Plaid documentation is well known for being really good:
  • Some sections of the guide allow the user to decide on their approach showing only relevant information (i.e. Docker vs Non Docker setup). This reduces the amount of reading the user has to do.
  • Contains troubleshooting tips - when combined with content that can be switched on/off it could improve the guide as the user could click a button "I can't find A" and the section for troubleshooting it would show then.
  • The guide keeps a light not overly technical nor overly formal tone which make the read quick and easy.
• Vue.js Quick Start - Vue Quick Start only provides means to set a project up and at the end it gives the user a choice of continuing learning the essentials or diving directly into examples.
  • The whole documentation is divided into several sections, where the first one is Essentials which is intended to be read one by one, but still works well when read at random. This allows users to learn the framework in smaller pieces and only initially only on a must-know basis that will let them do their work quickly and allow to understand more advanced topics when the time comes. The name Essentials also encourages users to focus on that section first.
  • Each article contains a button to go to the next article. This suggests that they're intended to be read in the specific order and reduces the need to go to the menu to select next article. This is especially convenient on mobile devices where it's more of a hassle to navigate through the menus.
• Vercel Getting Started - Whole first set of docs pages are called Get started.
  • Withing articles there are short sections in form of a question, like Using CLI? - when clicked they unfold a section providing more detail about the optional subject. This allows to keep the overall content short, while allowing edge-case users to get more info on their specific situation without switching to a different page.
  • The guide is split into several steps with optional sub-steps. In addition of the regular "next" button they are presented with options that allow them to decide which path they want to take. For example choosing between "importing existing project" or "creating one from template".
  • The guide ends with "Next steps" page, where user is presented with a variety of beginner-friendly topics leading to different parts of the docs.
• React Quick Start - A single-article approach to getting started that explains a variety of basic concepts without creating a sample project. Only at the end of the guide the user is directed to go through a more practical tutorial.
  • Begins with a clear section explaining what the reader will learn in the article
  • Refers to the reader as "you" instead of the usual "we"
  • Contains handy diagrams to help the reader understand the topic in a visual way
  • Utilizes line highlighting in code examples
• Svelte Tutorial - A hands-on introduction to the library in a small task-based examples that introduce all basic concepts one-by-one. This allows the user to try things out immediately and learn/experiment with the new skills as they learn them. Other frameworks/libraries start to borrow the format of the Svelte tutorial, for example Vue.js tutorial.
  • High engagement and high knowledge retention due to being hands-on
  • Quite feasible to implement in Val Town in case of single-val examples
  • Enhances the focus on a single topic that's being explained/demonstrated.

Decision points

Format

• Splitting the Getting Started into multiple pages - a series of shorter articles that are supposed to be read in order (numbered?)
• Keeping it as a single page for the sake of simplicity and approachability - all the most basic info in one place, but might be lengthy.

Interface explanation

How detailed should the UI introduction be?

• Which elements of the UI can be avoided during the initial tutorial?
• Should it include explanation of the entire UI to keep all info in one place and therefore mitigating the need for explaining things again in other pages?
• How to keep it easy to refer to in other pages?
• Make a separate UI explanation page that covers everything?

Dealing with UI changes:

• How to minimize the number of screenshots while keeping it clear for newcomers? - screenshots quickly go out-of-date
• UI changes affect not only the pictures but also text. Sometimes it might be less work to update a screenshot than to rework a text-only explanation.

How to keep it mobile friendly?

• What are the differences in the mobile/desktop interfaces?
• How important is mobile approach in coding platform?

[Steve Krouse]

Great start! Excited for the examples section!

[Xkonti]

@stevekrouse Updated the examples section. Do you have anything to add from your point of view?

[Steve Krouse]

Nice! Looks great! Keep going? Need anything else from me?

[Xkonti]

Ok. I'll work on overall structure proposal.