FujoWeb.dev writing style start

Author: essential-randomness

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "workbench.colorCustomizations": {
+    "commandCenter.border": "#15202b99",
+    "sash.hoverBorder": "#e7b423",
+    "titleBar.activeBackground": "#c29515",
+    "titleBar.activeForeground": "#15202b",
+    "titleBar.inactiveBackground": "#c2951599",
+    "titleBar.inactiveForeground": "#15202b99"
+  },
+  "peacock.color": "#c29515"
+}

astro.config.mjs

@@ -1,26 +1,32 @@
 // @ts-check
-import { defineConfig } from 'astro/config';
-import starlight from '@astrojs/starlight';
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
 
 // https://astro.build/config
 export default defineConfig({
-	integrations: [
-		starlight({
-			title: 'My Docs',
-			social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
-			sidebar: [
-				{
-					label: 'Guides',
-					items: [
-						// Each item here is one entry in the navigation menu.
-						{ label: 'Example Guide', slug: 'guides/example' },
-					],
-				},
-				{
-					label: 'Reference',
-					autogenerate: { directory: 'reference' },
-				},
-			],
-		}),
-	],
+  integrations: [
+    starlight({
+      title: "My Docs",
+      social: [
+        {
+          icon: "github",
+          label: "GitHub",
+          href: "https://github.com/withastro/starlight",
+        },
+      ],
+      sidebar: [
+        {
+          label: "Sociocracy",
+          items: [
+            // Each item here is one entry in the navigation menu.
+            { label: "Example Guide", slug: "sociocracy/example" },
+          ],
+        },
+        {
+          label: "FujoWeb.dev & FujoGuide",
+          autogenerate: { directory: "fujowebdev" },
+        },
+      ],
+    }),
+  ],
 });

src/content/docs/fujowebdev/formatting.md

@@ -0,0 +1,71 @@
+---
+title: Content Formatting
+sidebar:
+  order: 5
+---
+
+Our content is designed for _skimmability_: as you write it, imagine you’re only reading bits and pieces of it as you go in search of the sections most relevant to what you’re trying to do.
+
+### General Formatting
+
+- **Paragraphs:** Keep them short and (ideally) focused on one idea. Be generous with them\!
+
+- **Bold:** Use bold to highlight the main big idea in a series of paragraphs, or other crucial concepts. Try to highlight the content so it reads like a full sentence. For example: “As one of the most popular Version Control Systems, **Git helps you never lose track of changes to your code**, no matter how long it’s been since you last worked on it\!”
+
+  - How much of the sentence to highlight is a bit of an art\! Do your best to imagine what _you_ would want to see pop out of the page as you skim through it\!
+
+  - Make sure not to bold too often in a row, as it can get overwhelming and lose effectiveness.
+
+- **Emphasis:** We use _emphasis/italics_ to:
+
+  - Stress important points in sentences, e.g. pay _very close_ attention to the path you give to the `rm` command.
+
+  - Use emphasis to highlight technical terms that aren’t code commands (e.g. In coding, it’s often useful to use _relative paths_ for files and directories). This is inconsistent, and up for debate whether we should make this a standard advice.
+
+  - Group together longer titles without using “” (e.g. This articles are designed as companions to _FujoGuide Issue 1: Local Version Control with Git_, which you can buy…)
+
+- **Linking:** use links generously, and make sure you’re linking descriptive text (not “`click here`” but “`find the official documentation here`”). You should link to:
+
+  - Relevant articles from elsewhere on `learn.fujoweb.dev`, especially for prerequisites, terms definitions, or deeper knowledge
+
+  - Authoritative external sources (e.g. `MDN`, official tool docs)
+
+  - If we don’t have a guide, we might try to find a good substitute on the web. However, these links tend to rot.
+
+- **Lists:** Use lists generously, as they help with skimmability. You should:
+
+  - Use numbered lists for items in sequence (e.g. we’ll learn 1\) how to do A 2\) how to do B…)
+
+  - Use bullet point lists for key takeaways or items not in a sequence (like this list\!)
+
+  - Use [**Steps**](https://starlight.astro.build/components/steps/) for sequences of instructions
+
+### Code Formatting
+
+- **Inline Code:** We use inline code to highlight:
+
+  - Commands (e.g. `git commit -m “your message”`)
+
+  - File names (`index.html`), paths `~/my_site/`, keyboard shortcuts (`ctrl + k`) or tool names (`vim`, `zsh`)
+
+- **Code blocks:** Code blocks are an essential part of our guides, as they help people see how things work _in practice_ and help break the flow of the text (and aid in skimmability). You should:
+
+  - Make sure to explain what the code does and why it’s there
+
+  - Provide both input and output (unless confusing). You can omit part of the output if it helps the user focus on what you want to see. Similarly, you can make some output lighter to de-emphasize it.
+
+  - Use the code block captions to call out any particular element of the example you want the user to notice
+
+### Other Formatting
+
+- **Images:** Use images to show non-code results, UIs, or examples of programs in action. You can annotate if needed, but be mindful that it makes them harder to edit later.
+
+  - If you cannot provide ALT text yourself, let us know: we’ll get someone to write it for you.
+
+  - Use captions to help the reader understand what they’re looking at and what matters about it.
+
+- **Diagrams:** [We use Excalidraw for diagrams](https://excalidraw.com/). Make sure you download the `.excalidraw` file and not just the PNG.
+
+- **Tabs:** When a command differs across programs or Operating Systems, you can use [Tabs](https://starlight.astro.build/components/tabs/) to provide alternative versions of commands or explanations.
+
+- **More components:** we can easily use [all components from Starlight](https://starlight.astro.build/components/steps/). If you think a specific functionality not covered by these would help, you can ask Ms Boba whether it can be provided.

src/content/docs/fujowebdev/index.md

@@ -0,0 +1,52 @@
+---
+title: What is FujoWeb.dev?
+sidebar:
+  order: 1
+---
+
+Clear and approachable learning content for beginner-to-intermediate hobbyist
+web developers that is:
+
+- **Practical**, helping _hobbyists_ who want to hit the ground running get
+  started quickly
+- **Foundational**, clarifying concepts _hobbyists’_ guides gloss over to make
+  advanced tools accessible
+- **Encouraging**, deeply believing in the reader's ability to learn complex
+  subjects…
+- **Validating**, …while acknowledging the real struggles (and joys) of learning
+  web development
+
+But, above all:
+
+- <u>**Empowering**</u>, framing learning not as a chore, but as a tool to
+  reclaim a sense of control over the web and its endless possibilities of
+  creative expression and human connection
+
+## Our Audience
+
+Hobbyist web developers that aren’t (necessarily) building a coding career, but
+are drawn to the creative and practical possibilities of programming—especially
+when it comes to building tools for themselves and their communities.
+
+We assume they:
+
+- **Have already taken (basic) steps into programming**, but may be running
+  commands or copy-pasting code they don’t fully understand
+- **Are overwhelmed by the many paths and topics out there**, and are looking
+  for guidance on where to go next
+- **Are stuck in a learning limbo**, caught between hobbyist learning material
+  they outgrew, and hard-to-parse professional guides that don’t speak to their
+  needs
+
+:::note[Audience Demographic]
+
+As we write, we primarily imagine an audience that is:
+
+- **Very online**, aware of online memes and parlance
+- **Millennial**, coming online around the 00s-10s period (or wishing they had)
+- **Nostalgic**, of a time when the internet didn’t take itself so seriously and
+  possibilities felt endless
+- **Unapologetically passionate**, not afraid of being seen as “cringe” as they
+  dive deep into their interests
+
+:::

src/content/docs/fujowebdev/role-and-material.md

@@ -0,0 +1,36 @@
+---
+title: "Projects: FujoGuide & Co."
+sidebar:
+  order: 2
+---
+
+Our projects serve people in two ways:
+
+- **As they’re starting**, it gives them clear, actionable entry points to begin
+  tinkering with useful tools and languages
+
+- **As they’re growing**, it gives them a place they can revisit to renew and
+  deepen their understanding of the tools they’re using
+
+## Our Role
+
+\[We make choices about which technologies we use and talk about using
+these criteria:
+
+- Tools should be modern and be valid industry practice that is still useful to
+  people
+- We focus on the TypeScript language and ecosystem because \[\[reasons\]\]
+
+\]
+
+## Our Entry Points
+
+\[One of the goals of the FujoVerse™ is to create projects that entice and
+encourage people to take up programming, and FujoGuide is meant to be the answer
+as to how they can do that\]
+
+- \[BobaBoard can funnel people into learning collaborative and self-reliant
+  tools\]
+- \[Our NPM libraries encourage people to learn how to use NPM or get bolder
+  with their Astro websites\]
+- \[Fandom Coders …\]

src/content/docs/fujowebdev/structure.md

@@ -0,0 +1,57 @@
+---
+title: Articles Structure
+sidebar:
+  order: 3
+---
+
+Most articles benefits from the following flow:
+
+1. **Title:** clear and descriptive
+
+2. **Intro Section**
+
+   1. _Quick introduction to the article topic:_ a couple of sentences that help the reader understand whether they’re interested in the subject at all.
+
+   2. _“After reading this article, you’ll know”:_ a list of bullet points explaining the major topics the article covers, each linking to the specific section where the topic is presented. These will often correspond to section titles, but can use different language if needed to be descriptive.
+
+   3. _Prerequisites:_ let the reader know if they need specific knowledge before tackling this article. If we have articles covering this knowledge, make sure to link to them.
+
+3. **Article Sections**
+
+   1. Use descriptive section titles. It’s ok to be a bit funny, if things remain clear in context (e.g. “`The nuclear exit option`”, “`Forcing TypeScript to Shut Up`”)
+
+   2. Use subsections generously. Think about where a confused friend could use a reference to a specific subsection\!
+
+   3. Show practical examples whenever you can. For example, by showing a sample of commands and outputs that illustrate the topic in practice.
+
+      1. When you choose a command make sure that its level is appropriate to the current level of the audience (e.g. they might not know what “changing a port” means).
+
+      2. Good commands depend on the article and its positioning in the surrounding content ecosystem, but they generally tend to be basic, of broad usefulness, and easy to understand (e.g. `ls` in terminal, or `npm install`).
+
+      3. Rule of thumbs for choosing commands or examples:
+
+         1. Do they already know them? Is this something they’re likely to want to do often? IF NOT,
+
+         2. Do we expect them to learn about it soon? Would it be useful for them to learn this at this stage? IF NOT
+
+         3. Can we explain in simple words why something would be useful to them, even if they don’t have the full context or appreciation of the topic?
+
+   4. **Use callout boxes/asides for:** _(note**:** we aren’t always using these right in our current material)_
+
+      1. **`::note`:** Information that is helpful to know but that isn’t solving an immediate problem. Might be minor clarifications that enhance understanding without being critical, alternative approaches, or interesting background. _Examples include_: historical reasons for design choices, alternative tools, gentle reminders of past concepts.
+
+      2. **`:::tip`:** Best practices, clever shortcuts, _great_ advice, or links to related guides. These are positive suggestions that will help people work smarter, get over anxieties, or learn more about the topic. _Examples include_: common keyboard shortcuts, optional (but useful) features, “this is hard for experts too”, links to deeper explanations of related topics.
+
+      3. **`:::caution`:** A common pitfall, error, or unexpected behavior that might lead to frustration (bugs, wasted time...) but not cause irrecoverable loss or security/privacy risks. _Examples include_: this command requires absolute file paths, if this setting isn’t configured you might encounter an error.
+
+      4. **`:::danger`:** things that can go very wrong, either in unrecoverable ways, or with significant negative consequences\! _Examples include:_ making sure readers know about the dangers of `rm -rf`, or things that might accidentally cause privacy leaks (e.g. `git` user settings).
+
+      A callout box can also include a collapsed section for further explanations that are not necessary and might be overwhelming to the casual reader. The callout box should still include a broad overview of the topic to help the reader determine whether they want to read further. The collapsed elements should have descriptive titles so readers know whether to open them\!
+
+4. **Outro Section** (note: we don’t really have this now, but we should)
+
+   1. _A short summary_ of what the reader can now do thanks to what they learned.
+
+   2. _Suggestions for next steps:_ could be other articles (“`Now that you know how to open a terminal, you can learn how to run programs or navigate your filesystem`”), or an invitation to try things out (“`Now try building your own NodeJS programs`”).
+
+   3. If relevant, a call to action to check out our paid offerings (like the Git zine).