import { Contributors } from "~/components/contributors/Contributors";
Welcome to Solid's new docs site! These pages are the beginnings of our new effort, and we're super excited for you to join us.
Solid is a front-end framework for building web apps. It's designed to have a great developer experience, and we want the docs to match, both in terms of being beginner-friendly and showcasing the usability of the framework.
Learn about Solid in 100 seconds.
The existing documentation was originally written by the framework author and edited by the community. There is an interactive tutorial that explains how to use each of the framework's features - it's more like an interactive reference. We also have guides that were originally adapted from blog posts. The API Reference serves as a comprehensive technical reference document.
Here are some issues we've noticed and received feedback about:
- The tutorial isn't beginner friendly; it assumes technical knowledge that many beginners don't have.
- We have a lot of information on the framework itself, but not much on how to use the framework in real-world applications.
- Our guides are informative but not easy to follow.
- It's not clear where to go when you're looking for help with something specific.
- We don't answer the question "how do I build an app from scratch?"
- Our docs are too academic/technical.
Rather than editing the existing docs, we decided to make a new docs site to start fresh with structure, content, and voice. We also started a Docs Team and made it clear that docs are a Core concern.
The new site uses a writing tool called mdx, which is an extension of Markdown that allows us to experiment with embedded rich components.
We wrote out writing principles and a new structure that follows the Diataxis model. We want our guides to include both project-based tutorials and topic-based how-to guides, and we want our reference section to not just include API reference, but concept explanations inspired by Diataxis's "Explanation" category.
We're also exploring video content - we see a lot of potential in video tutorials and docs companion videos.
If you're here from the Write the Docs conference, we'd love your thoughts on our plan and our first steps. This is a volunteer, open-source effort, and we're always looking for new contributors, whether it's to focus on a specific piece of content or to join the docs team!
Outside of the conference, our main point of communication is Solid's Discord. Once you're there, check out the #docs channel. You can also contact @jutanium on Discord (or on Twitter if you haven't joined us yet!).
We're looking for anyone who cares about communication. If you've never written a line of JavaScript and are interested in what we're doing, we want to teach you. The more outside and diverse perspectives we have, the better our team will be.
- Erik Demaine - API reference maintenance
- Nikhil Saraf - SolidStart site infrastructure
- Oren Elbaum - Diving Deeper sections