The New Solid Docs

Welcome

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, or watch a more detailed intro made by our docs lead.

Current documentation

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.

How we're approaching new docs

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're following 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.

How to get involved

Start with our Contributing Guide and our Writing Guide.

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 help you learn Solid so you can teach others. The more perspectives we have, the better our team will be.

Thanks to our docs contributors

GitHub user crutchcornGitHub user kaleem68GitHub user Yan-ThomasGitHub user chisom5GitHub user mdynnlGitHub user kidonngGitHub user snewell92GitHub user nas5wGitHub user nksarafGitHub user nsarafpureGitHub user teenjunaGitHub user JutaniumGitHub user boehsGitHub user edemaineGitHub user kkharjiGitHub user iainsimmonsGitHub user islambegkGitHub user PancfGitHub user PriestchGitHub user anderskGitHub user FluidSenseGitHub user BjornvdbGitHub user GreatGuy96GitHub user nelsonmicGitHub user Hopelezz