Devour/devour_data/docs/writing.json

{
  "id": "05854ac817c704a1fa5d9330",
  "source": "solid:signals",
  "type": "github-document",
  "title": "WRITING",
  "content": "# Solid Docs Writing Guide\n\n## Introduction\n\nThank you for your interest in writing for Solid.\nThis writing guide is in-progress, so please be sure to check it often as we adjust things.\nWe welcome suggestions and feedback.\n\nBear in mind that the following is a general guideline, but we will use it as a framework to edit any incoming contributions.\nThis is to ensure that Solid's documents remain consistent in tone, voice, structure, and conventions.\n\n## Visual style\n\nSolid wants to maintain a consistent brand across all of its documentation.\nWe want to present a consistent and professional face to our users and partners.\nAs such, we have several guidelines that will dictate how your contributions will look once published.\nWhile it would be great if you followed these exactly — and our contributing editors would sure love you for it — we know that you'd probably prefer to focus on getting great Solid content ready to go.\n\nSo please try to follow this visual framework as best as you can to make the process as smooth as possible.\nOf course, trends in documentation styling change over time, so we're fully aware that these guidelines will likely shift as we consider adopting new best practices.\n\n### Layout\n\nThe bulk of your contributions will be the body copy.\nBut beyond just your written content, there are several other things to consider while working on your document.\n\n#### Tables\n\nThough not used all that often, tables are an important tool for several reasons:\n\n- They break up text.\n- They offer clear information to the reader.\n- They are easy to look through and understand.\n\nSolid uses Markdown for tables, so here's how to make one.\n\n1. Start with a vertical line, also called a pipe: `|`.\n2. Insert your first heading and end with another pipe.\n3. Write the next heading and end it with a pipe. Repeat until you have your column headings.\n4. One line under the first column heading, insert at least three dashes: `---`.\n5. Repeat this for all of your headings.\n6. To create the cells, start a new line with a pipe, then insert the content and surround it in spaces, end the cell with a pipe.\n7. To complete the row, create a new cell on the same line.\n\nSee below for an example of what this would look like in raw Markdown.\n\n```\n| Month | Day |\n| --- | --- |\n| January | 1 |\n| February | 2 |\n| March | 3 |\n|April | 4 |\n```\n\n#### Asides\n\nAsides serve as callout boxes in Solid's documentation.\nThey represent a section of the document that is related to the content surrounding the aside, but not directly relevant to the page.\nThey work well with explaining how Solid differs from other popular frameworks, referring to other points in the documentation, or serving as a tangential note.\nWe ask that you use them sparingly.\n\n1. To use an aside, you must first import the correct component.\n2. Use the following command in your terminal. (Remember to be in the cloned Solid repo directory.)\n\n3. Once you have the Aside component imported, simply follow the below example for how to add one to your document.\n\n```\n:::note\n    content here\n:::\n```\n\n### Code examples\n\nSolid's documentation contains example code, like you've seen here in this guide.\nMarkdown lets you create inline code and code blocks.\n\nIf you want to call out a single command or a file path, surround the text with single back ticks: `.\n\nHere's an example in raw Markdown:\n\n```\n`npm`\n```\n\nIf, however, you need more than that, then a code block is more appropriate.\nStart with three back ticks, ```, write your code, then close the block with three more back ticks.\n\nHere's an example in raw Markdown:\n\n````\n```bash\nnpm install\n````\n\nCode examples are vital to providing users with quick tips on how to use Solid.\nKnowing when to use inline code versus code blocks can further the understanding of the readers and users alike.\n\n### Images\n\nGood documentation takes advantage of images, such as screenshots and graphics, to expand upon the written content.\nImages should not introduce or explain something new.\nThey are used in addition to the writing, such as increasing a reader's understanding, communicating ideas, emphasizing points, or providing a comparison.\n\nTo maintain some consistency, we would prefer that you stick to the PNG format so that the images scale well at all screen sizes and resolutions.\nPlease avoid using GIFs if at all possible because they interfere with accessibility.\n\nFinally, we strongly request that you use alt text with your images.\nThis is very important for our accessibility initiatives.\nIf you are adding an image to a page, you can do that using HTML syntax.\n\nHere's an example of how to do that:\n\n```\n\u003cimg src=\"IMAGE.png\" alt=\"alt text here\" /\u003e\n```\n\n## Organization\n\nNow that we've laid out how we'd like your contribution to look, we'd like to take a moment to discuss how we'd like to see it organized.\n\nPlease note that, for editing purposes, **each sentence gets its own line**.\nParagraphs should have two lines between them.\n\n### Headings\n\nHeadings act as the primary means of document organization.\nSolid uses Markdown, which means headings are defined by hashes `#` followed by a space.\nFor each additional hash, you go down one heading level.\n\nHere's an example of a Heading 1 (H1) and a Heading 2 (H2) in raw Markdown.\n\n```\n# Solid documentation\n\n## Introduction\n```\n\nWe primarily use Headings 1 through 3.\nHowever, headings can go up to 6.\nNote we rarely use Headings 5 and 6.\n\nBelow is a quick breakdown on the different headings.\n\n```\nH1: Title\nH2: Main sections\nH3: Subsections\nH4: Small details you would like to call out\nH5/H6: Advanced concepts\n```\n\n### Lists\n\nYou will come across two types of lists in your contributions, ordered and unordered.\nHere's a breakdown on when to use each one.\n\nOrdered: This is for step-based, how-to content.\nYou need an ordered list when the order or hierarchy is important.\n\nUnordered: Unordered lists help break up content with non-hierarchical items.\nYou will likely use them when writing exceptions and emphasizing important ideas.\n\nIn addition to these two types, you might need to use a nested list.\nThis is for when a listed item has a sub-part to it that is relevant to its content.\n\nFinally, you may come across a point where you need to make a note on a listed item.\nThis would be an area where a nested point would not be appropriate.\nThese notes might link out to another part of the documentation or a piece of reference material; or, they may also inform the reader about a warning or a gotcha.\n(Gotchas are unexpected and/or unreasonable outcomes that the reader should know about. An example is a command that is similar to the one you listed, but using it would cause some kind of issue.)\n\n### Page linking\n\nWe would prefer you to keep page linking in mind while you're working on your contribution.\nThe following two points are what you should pay attention to:\n\n1. Interlink when you refer to a topic that has its own page.\n   This makes it possible for the user to easily seek additional information.\n2. Be descriptive with the linked text.\n   Do not use \"click here\" or any variation therein, as this is not a best practice for accessibility.\n\nLinks are written in Markdown.\nHere's an example of what that looks like:\n\n```\nDo: Check the [Solid homepage](https://www.solidjs.com)\nDon't: Click [here](https://www.solidjs.com) to go to the Solid homepage.\n```\n\n## Reference pages\n\nReference pages document the API surface.\nKeep them concise and easy to scan.\n\nInclude:\n- Imports\n- Signatures\n- Parameters\n- Return values\n- Short examples\n\nAvoid:\n- Narrative context or “why”\n- Usage guidance (“when to use”, best practices)\n- Long notes\n\nIf explanation is needed, link to a guide or how-to page.\n\n## Voice and tone\n\nSo far, we've dealt with how your contributions should look and function.\nAs important as all of that is, the core part of your documents is the writing itself, so we want to discuss how we would like our documentation to read.\n\n### Approachable\n\nModern documentation has shifted toward a less formal tone to great effect.\nLike modern documents, Solid aims to provide a friendly and approachable tone.\nOf course, your contributions should still maintain a technical focus to provide the reader with the information that they're looking for.\nWe encourage you to pay attention to how [Google](https://developers.google.com/style/tone) defines a friendly tone.\n\n\u003e In your documents, aim for a voice and tone that's conversational, friendly, and respectful without being overly colloquial or frivolous; a voice that's casual and natural and approachable, not pedantic or pushy. Try to sound like a knowledgeable friend who understands what the developer wants to do.\n\nThe old way of writing documentation — the dry, formal, and very rigid method — created a divide between the reader and writer.\nWe don't want that here.\nWe want our users to enjoy reading Solid's docs so that they retain the information they came here for.\nThis requires writing engaging content that is also approachable for most skill levels.\n\nThe tricky part for you is determining that baseline skill level.\nSolid caters to a more technically advanced audience, the members of which are more likely to know what you might consider to be basic knowledge.\nHowever, in the introductory documentation especially, we should be offering written work that is approachable even to beginners.\nWe'll discuss more what that looks like later, but just remember these two questions when considering your contribution's approachability.\nWho is the document for?\nWhat would I be looking for if I was coming to this document for the first time?\n\nPlease keep in mind, do not write like you are present with the user.\n\n```\n- Do: Visit Solid's homepage.\n- Don't: We're going to visit Solid's homepage.\n```\n\nWhen writing steps in a how-to section, please start sentences with a verb.\n\n```\n- Do: Download npm.\n- Don't: You will/should download npm.\n```\n\n### Accessible\n\nAccessibility has taken a front seat in most aspects of technology in recent years, including documentation.\nSolid should be accessible to anyone who wishes to use it, meaning that your writing has to meet some basic standards.\n\nSome accessibility comes down to visual style, as we discussed.\nHowever, it goes hand-in-hand with inclusiveness (which we'll get to next), so there is some overlap between the two.\nFor now, we ask that you understand that Solid wants to ensure that everyone can read our documentation.\nWhat does that look like?\n\nThe first step towards accessibility is using proper English grammar.\nThis is especially helpful for those users who utilize screen readers.\nAnother way you can help the users of assistive technology is by keeping your paragraphs reasonably short.\nA good rule of thumb is no more than four sentences, or four to five lines of text.\n\nShorter paragraphs help readers of all abilities, since walls of text can discourage in-depth reading and understanding.\nYou can once again practice empathy here.\nWhat would you like to read?\n\nAs discussed in the Organization section, ensuring a strong layout is key to accessible documentation.\nWe encourage you to remember that your contributions should be organized logically.\nHeadings that give a strong indicator of the section's topic, as well as descriptive hyperlinks, go a very long way in helping our readers navigate our docs.\n\n### Inclusive\n\nGreat documentation strives to be as inclusive for as many people as possible.\nThat includes those from different backgrounds, such as varying countries and languages.\nAs Solid grows, so will its audience, and therefore we should work hard to ensure that everyone feels included while reading our docs.\n\nWhat does inclusive language look like?\n\nFirst, we want to focus on using plain, simple English.\nThat means avoiding the use of jargon wherever possible.\n(We know that in more advanced documents, this becomes nearly impossible.)\n\nIn cases where jargon is necessary, be sure the document contains at least one brief description upon the first mention.\nFor example, if you want to use an acronym, spell it out first with the acronym in parentheses after.\nFrom then on, you can use the acronym in that document.\n\nPlain and simple English also means avoiding contractions, as these are not always easily understood by those for whom English is not the first language.\nWe should also avoid using expressions or figures of speech wherever possible; remember, not everyone will understand what they mean.\n\nSecondly, inclusive language means remaining as gender-neutral as possible.\nInstead of defaulting to one gender, use a gender-neutral word instead.\nAs mentioned previously, we want to use friendly, second-person language to help connect our readers with our documentation.\nDoing so makes it fairly simple to avoid gendered words.\nUse your own common sense to determine which word to use, but if you slip up, an editor should catch it.\n\nWriting inclusively also entails avoiding ableist language.\nThat usually comes about in certain turns of phrase.\nAlternatives to ableist words will go a long way to ensuring our documentation meets the needs of more people.\n\nSimilarly, we should not use divisive terms to get our point across.\nThat means steering clear of socially- and racially-charged language for concepts, such as \"blacklist\" or \"first-class.\"\n\nWe have chosen to use American English in our documentation, so please remember that especially with spelling.\n\nDespite us aiming for an informal tone, that does not mean that we want to get too lax in our language.\nWe should try to avoid too many references to a specific culture (e.g. American).\nSolid has a large North American audience, but our readers are not exclusive to that region.\nPlease keep this in mind before you use a certain term or phrase.\n\nWhen it comes to the topic of inclusion and inclusive language, empathy is critical.\nOnce again, ask yourself throughout your writing process: Who is this document for?\n\nFor more on what inclusive language looks like, [Google once again has a great breakdown](https://developers.google.com/style/inclusive-documentation).\n\n## Solid Terms\n\nThis is a list of Solid-specific words and what they mean. In the second column, we put:\n\n- Terms that mean the same thing but shouldn't be used for the sake of consistency.\n- Terms that mean something different and are easy to confuse with the term at hand\n\nThese are technical; use them with the default assumption that the reader doesn't know what they mean.\n\n| Terms to use                      | Terms not to use                                                   | Definition                                                                                                                                                                               |\n| --------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Computation, reactive computation | _Not to be confused with_: computed                                | A scope that automatically reruns when its dependencies change (it doesn't necessarily _have_ dependencies).                                                                             |\n| Core primitive                    | API function                                                       | A primitive provided by the Solid core library; this typically provides reactive behaviors but not necessarily ( `createContext` does not).                                              |\n| Custom primitive                  | hook                                                               | A primitive created outside of the Solid core library; i.e., a function that provides a composable piece of functionality.                                                               |\n| Ownership, owns                   |                                                                    | A one-to-many relationship between computations; if a computation \"owns\" one or more other computations, all its owned computations are cleaned up when it is cleaned up.                |\n| Primitive                         | Hook                                                               | A function that serves as a building block of reactivity or behavior. usually begins with `create` or `use`.                                                                             |\n| Reactive value                    | Signal (don't use to describe a general reactive value)            | A value that can be tracked (includes signals, memos, properties of `props` and stores).                                                                                                 |\n| Reactivity                        |                                                                    | A system for writing expressions or behaviors that depend on certain values and execute when those values change.                                                                        |\n| Root                              |                                                                    | A computation that has no owner. created by `createRoot`.                                                                                                                                |\n| Scope                             | _Not to be confused with:_ root, effect (specific kinds of scopes) | A body of a function (a chunk of code).                                                                                                                                                  |\n| Solid                             | SolidJS (unless outside the community/internal writings)           | A JavaScript framework made up of a library (providing primitives and UI utilities) and a compiler (allowing you to write in JSX). Its differentiating feature is its reactivity system. |\n| Tracking scope                    | Tracking context, reactive context, reactive scope, reactive root  | A scope that, when run, Solid automatically tracks all read signals                                                                                                                      |",
  "url": "https://github.com/solidjs/solid-docs/blob/HEAD/WRITING.md",
  "metadata": {
    "path": "WRITING.md",
    "repo": "solidjs/solid-docs",
    "repo_url": "https://github.com/solidjs/solid-docs.git",
    "size": 18321,
    "source_type": "github"
  },
  "hash": "9405ea1f99eb2def66fc13645189f715d2d218ae4784407d9fd4db42ca7a99a6",
  "timestamp": "2026-02-23T11:43:00.185882585+01:00"
}