From 216f1662ff706633754e643398c5397d2afae8d3 Mon Sep 17 00:00:00 2001 From: Rie Date: Sun, 15 Feb 2026 03:40:35 +0000 Subject: [PATCH 1/3] Updated Article Guidelines and Writing Style --- package-lock.json | 7 + .../docs/fujowebdev/style-guide/index.md | 2 +- .../docs/fujowebdev/style-guide/structure.md | 78 +++-- .../docs/fujowebdev/style-guide/style.md | 281 ++++++++++-------- 4 files changed, 221 insertions(+), 147 deletions(-) diff --git a/package-lock.json b/package-lock.json index c277422..a26c321 100644 --- a/package-lock.json +++ b/package-lock.json @@ -105,6 +105,7 @@ "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.36.1.tgz", "integrity": "sha512-Fmt8mIsAIZN18Y4YQDI6p521GsYGe4hYxh9jWmz0pHBXnS5J7Na3TSXNya4eyIymCcKkuiKFbs7b/knsdGVYPg==", "license": "MIT", + "peer": true, "dependencies": { "@astrojs/markdown-remark": "^6.3.1", "@astrojs/mdx": "^4.2.3", @@ -1676,6 +1677,7 @@ "version": "8.15.0", "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -1838,6 +1840,7 @@ "resolved": "https://registry.npmjs.org/astro/-/astro-5.14.8.tgz", "integrity": "sha512-nKqCLs7BFvGQL9QWQOUqxHhlHtV0UMLXz1ANJygozvjcexBWS7FYkWI2LzRPMNYmbW4msIWNWnX2RvLdvI5Cnw==", "license": "MIT", + "peer": true, "dependencies": { "@astrojs/compiler": "^2.12.2", "@astrojs/internal-helpers": "0.7.4", @@ -4961,6 +4964,7 @@ "url": "https://github.com/sponsors/ai" } ], + "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -5495,6 +5499,7 @@ "version": "4.44.1", "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.44.1.tgz", "integrity": "sha512-x8H8aPvD+xbl0Do8oez5f5o8eMS3trfCghc4HhLAnCkj7Vl0d1JWGs0UF/D886zLW2rOj2QymV/JcSSsw+XDNg==", + "peer": true, "dependencies": { "@types/estree": "1.0.8" }, @@ -6370,6 +6375,7 @@ "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.1.tgz", "integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==", "license": "MIT", + "peer": true, "dependencies": { "esbuild": "^0.25.0", "fdir": "^6.4.4", @@ -6564,6 +6570,7 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/src/content/docs/fujowebdev/style-guide/index.md b/src/content/docs/fujowebdev/style-guide/index.md index 2a22584..9852e44 100644 --- a/src/content/docs/fujowebdev/style-guide/index.md +++ b/src/content/docs/fujowebdev/style-guide/index.md @@ -7,7 +7,7 @@ sidebar: :::caution This style guide is an older version we've been reworking. New one will be -published soon. +published soon! ::: diff --git a/src/content/docs/fujowebdev/style-guide/structure.md b/src/content/docs/fujowebdev/style-guide/structure.md index e12d525..553852b 100644 --- a/src/content/docs/fujowebdev/style-guide/structure.md +++ b/src/content/docs/fujowebdev/style-guide/structure.md @@ -1,57 +1,87 @@ --- -title: Articles Structure +title: Articles Guidelines sidebar: order: 3 --- -Most articles benefits from the following flow: +# **Article Guidelines** -1. **Title:** clear and descriptive +## **Article Function** + +All articles should follow three key principles: + +1. They answer a key question in the web development journey. + +For example: “What is NPM?” Or, “Why use JS?” + +When you’re writing an article, always circle back to your main question, and ask yourself if what you’re writing is building on the answer or if it’s derailing into a separate topic. + +A lot of web development topics are tightly interconnected: try to balance the need to position the information within the larger picture, and not overwhelming our audience by obfuscating the path ahead. + +2. Less is more: you should be precise, concise and factual. + +For example: Instead of “*To correctly use arrays, we must give them a name. This name will then be referred to as a variable that can be referenced in the code.*” We prefer: “*To give a name to an array, we assign it to a variable.*” + +When you’re writing an article, try to keep a simple sentence structure. Actions and consequences should be clearly defined and follow logically in the text. Prioritize actions over descriptions, clearly stating the “*who*”, “*what*”, “*where*” and “*when*”, for step-by-step guides. + +We expect our work to be used as reference material, which means our audience will come back to it when they need a reminder and will skim through to find the piece they’re missing. Make it easy by structuring things logically and avoid burying important information in large paragraphs. + +3. Every part of the article should add value to the whole. + +Not only the words you use, but the formatting you choose should be looked at from this angle. Ask yourself, “*what is the value added by…?*” when it comes to adding sections or asides. + +We must balance the casual tone of our overall communication with the volume of information we’re providing, and make sure we’re not burying our readers on either too much detail or too much chatter. + +In general, think of our articles as your response when a friend asks you a technical question: Yes, you want to make sure you don’t come across as pedantic or overwhelming, so you keep the friendly tone, but you should respect your friend and answer as clearly as you can. + +## **Article Structure** + +1. **Title:** It should be clear and descriptive. Think about the question the article is answering, and how to make it searchable and easily identifiable by the reader. 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. +* *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. +* *“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. +* *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`”) +* 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\! +* 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. +* 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). + * 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`). + * 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: + * 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, + 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 + 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? + 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)_ +* **Use callout boxes/asides for:** - 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. + * **`::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. This should be short and help contextualize information, but not derail the article. - 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. + * **`:::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. + * **`:::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). + * **`:::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). Make sure that if you call out a potential pitfall, you *also* call out the solution. Or at least *a* solution, or how to prevent it. Do not say “Don’t do X” and leave it at that. Instead try “Don’t do X, do Y instead.” - 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\! +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. +* *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`”). +* *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). +* If relevant, a call to action to check out our paid offerings (like the Git zine). diff --git a/src/content/docs/fujowebdev/style-guide/style.md b/src/content/docs/fujowebdev/style-guide/style.md index eabe86f..19ad4bb 100644 --- a/src/content/docs/fujowebdev/style-guide/style.md +++ b/src/content/docs/fujowebdev/style-guide/style.md @@ -4,130 +4,167 @@ sidebar: order: 4 --- -This guide is here to create a consistent style our readers can come to trust and learn from. +# **Writing Style** -When writing for FujoGuide, **think of yourself as a** **knowledgeable friend**, rather than a formal instructor. You deeply want the reader to succeed, have a strong belief in their abilities, and yet relate to their present struggles—you too have been an _intimidated beginner_ once\! +This guide is here to create a consistent style our readers can come to trust and learn from. At all times, we must balance technical knowledge with the casual, friendly banter of hobby spaces. -## Tone and Voice +When writing for FujoGuide, **think of yourself as a knowledgeable friend**, rather than a formal instructor. You are deeply invested in the reader’s success, have a strong belief in their abilities, and yet relate to their present struggles—you too have been an *intimidated beginner* once\! -Your tone should balance credibility and approachability by being: - -- \[TODO: use “you” \] - -- **Practical & Instructional** - - - **Do:** Focus on the _hows_ and the necessary _whys_ - - - **Do:** State prerequisites clearly, and explain how to fulfill them - - - **Do:** Highlight the value of what you’re teaching (“`a good git config will save you future pain!`”, “`Using a terminal will unlock new useful tool`”) - - - **Do:** Give accurate explanations, using consistent terminology paired with clear steps and examples - - - **Don’t:** Downplay your expertise\! You worked hard to know all you know. - - - **Don’t:** Assume previous knowledge without stating your assumptions - - - **Don’t:** Be unnecessarily pedantic—it’s ok to omit corner cases when they don’t provide value - -- **Approachable & Conversational** - - - **Do:** Use contractions (like `you’ll`, `it’s`, `don’t`) - - - **Do:** Talk directly to the reader using `you/your` - - - **Do:** Use clear and direct language, with simple words and sentence structures (when possible) - - - **Do:** Use accurate terminology, explaining common jargon and acronyms. - - - **Do:** Use analogies when clear and appropriate - - - **Don’t:** Sound condescending (be _very careful_ with `obviously`, `simply`, `just`—use them to encourage, not to downvalue\!) - - - **Don’t:** Use academic or jargony terms hobbyists won’t encounter in practice (e.g. `asymptotic complexity`, `third normal form`, `merkle tree`), unless appropriate for an aside. - - - **Don’t:** Force analogies that excessively oversimply concepts without adding real value or risk coming across as “talking down” - -- **Empathetic & Reassuring** - - - **Do:** Acknowledge difficulties (“`This part can be tricky…`”, “`It’s normal to struggle with…`”) - - - **Do:** Give encouragement and support (“`Take a deep breath`”, “`You got this!`”, “`It may seem hard, but you will master it`”) - - - **Do:** Demystify people’s beliefs about experts (“`Professionals are always looking stuff up…`”, “`The terminal/shell terminology is not used consistently…`”, “`Many programmers don’t know how to exit Vim`”) - -- **Genuine & Empowering**: - - - **Do:** Use light humor if it fits naturally. Mildly obscure references are ok, if timeless and unobtrusive to outsiders. - - - **Do:** Think back to your personal experiences, fears and frustrations - - - **Do:** Help people dream about future possibilities their newfound knowledge will unlock - - - **Don’t:** Try too hard to be funny - - - **Don’t:** Imply there’s a unique or uniform learning path, or a single way to be an expert - -## Language in Practice +## **Tone and Voice** -This section helps us craft effective explanations that are easy to parse and absorb. These rules aren’t meant to be prescriptive, but are a starting point to craft sentences from, and a tool to review them with: - -- **Language:** Stick to standard American English. Online parlance is welcome when appropriate. - -- **Be clear:** Prioritize direct, unambiguous writing. - - - Use language well: - - - Prefer an active voice to be more direct, clear, and engaging—unless it makes a simple explanation convoluted\! - - - Cut unnecessary words (“`in order to => to`”) - - - Prefer strong verbs over nouns (“`perform an installation => install`”) - - - Prefer positive framing when you’re not giving an explicit warning (“`Don’t do [x] unless [y] => if [y] do [x]`”) - - - Use transition words to smooth connections between sentences and paragraphs - - - Get to the point quickly: - - - When introducing a concept, start with a straightforward definition (“`Git is a program to manage changes to your files…`”, “`Absolute file paths specify the file location starting from the root…`, “`Commands are instructions you give to your Terminal…`”) - - - When explaining how to achieve a goal, prefer stating the goal first (“`To install a new library, you can run npm add [x]`”, “`To know the directory you’re currently in, use the pwd command`”) - - - Break down complex ideas in multiple sentences and paragraphs. If a sentence is getting long, consider: - - - moving the subject or central point closer to the beginning - - - reframing it as multiple sentences - - - using bullet points to break it down into parts - -- **Be concise but complete:** Make sure you cover the important parts without long-winded explanations. Respect readers’ time and attention span\! - - - The main content should prioritize information that is useful (the reader will need it to achieve their goals) and timely (is relevant to what they’re _currently_ learning) - - - If an important explanation doesn’t quite fit, consider whether it can: - - - be featured in a more appropriate place - - - grouped with other useful explanations to create a larger topic - - - Use asides to call out special cases, or to give more advanced explanations most readers can safely skip - -- **Pay attention to terminology:** - - - **Be consistent:** Use the same terms throughout the article and match the rest of the site–let us know where we got this wrong ourselves\! - - - **Define key terms:** Clearly define terms and concepts when you first introduce them. Use bold to highlight the core part of the explanation to aid skimmability. Make sure the bold part reads like a sentence\! - - - **Spell out acronyms:** When you introduce an acronym, explain what it stands for. You can choose whether to use: - - - **Term (acronym):** if the full term is common or it helps initial understanding (“`A Version Control System (VCS) helps people…`”) - - - **Acronym (term):** if the acronym is frequently encountered in the wild (“`NPM (Node Package Manager) is a powerful tool that…`”) - - - **Separate Sentences:** if the expansion requires more context or you want to elaborate on its meaning (“`HTML defines the structure of your websites. Its name stands for HyperText Markup Language, highlighting its ability to…`”) - - - **Clarify confusion:** explicitly call out terms that are often mixed up (e.g. `terminal program` vs `script` vs `command`) and differences across systems (e.g. `path separators`). When the differences are not important, acknowledge that and, if needed, add further explanations in an aside. +Your tone should balance credibility and approachability by being: -- **\[avoid filler words\]** +**Practical & Instructional:** + +* Set clear expectations for the reader and stick to what you’ve outlined. +* Keep steps simple: one action per step. +* Action and consequences should be clearly labeled and follow logically. +* Write with the expectation that your reader is following along with your instructions, so don’t lead them to a metaphorical cliff without warning clearly that the risk is there + +| Do | Do not | +|-----|-----| +| | | + +**Approachable & Conversational:** + +* Your reader should feel spoken to, not lectured at. +* The occasional meme or inside joke to break the tension is welcome, as long as it doesn’t derail the flow of information. +* Keep the wording simple and accessible. +* Don't be afraid of teaching people technical jargon when appropriate, but make sure to define it clearly in approachable terms. + +| Do | Do not | +|-----|-----| +||| + +**Empathetic & Reassuring:** + +* Remember, friends helping friends is the goal. +* Our audience comes to us for help, trusting that we won’t judge them for struggling, and we’ll do our best to answer in a way they can understand. +* Our goal is to empower our audience to use this knowledge in their own projects. + +| Do | Do not | +|-----|-----| +| || + +**Genuine & Empowering:** + +* There’s no single right way of doing things: what we offer is a specific option. +* Our ulterior motive is to unlock coding as a path for self-expression, not to dictate what that self-expression should look like. +* Avoid hierarchical speech: we’re all peers helping each other. +* We do this because we *genuinely* love technology and the possibilities it unlocks, and want our friends to love it and use it too. + +| Do | Do not | +|-----|-----| +||| + +## **Language Conventions** + +The following conventions help us craft effective explanations that are easy to parse and absorb. These rules aren’t meant to be prescriptive, but are a starting point to craft sentences from, and a tool to review them with: + +* **Language Standard:** + * Stick to standard American English. + * Online parlance is welcome when appropriate. + * Be mindful of slang that can be misconstrued as aggressive, negative or hurtful. + * Use inclusive, neutral language. + * Avoid making readers feel ostracized because they don’t understand the references or jokes. + * Hate speech has no place in our work. + * Do not make people or categories of people the butt of the joke. + +* **Language Clarity:** + * Prioritize direct, unambiguous writing. + * Use language well: + * Prefer an active voice to be more direct, clear, and engaging—unless it makes a simple explanation convoluted! + * Cut unnecessary words (“`in order to => to`”) + * Prefer strong verbs over nouns (“`perform an installation => install`”) + * Prefer positive framing when you’re not giving an explicit warning (“`Don’t do [x] unless [y] => if [y] do [x]`”) + * Use transition words to smooth connections between sentences and paragraphs. + * Get to the point quickly: + * When introducing a concept, start with a straightforward definition (“`Git is a program to manage changes to your files…`”, “`Absolute file paths specify the file location starting from the root…`, “`Commands are instructions you give to your Terminal…`”) + * When explaining how to achieve a goal, prefer stating the goal first (“`To install a new library, you can run npm add [x]`”, “`To know the directory you’re currently in, use the pwd command`”) + * Break down complex ideas in multiple sentences and paragraphs. If a sentence is getting long, consider: + * moving the subject or central point closer to the beginning + * reframing it as multiple sentences + * using bullet points to break it down into parts + +* **Economy of Language:** + * Make sure you cover the important parts without long-winded explanations. Respect readers’ time and attention span\! + * The main content should prioritize information that is useful (the reader will need it to achieve their goals) and timely (is relevant to what they’re *currently* learning) + * If an important explanation doesn’t quite fit, consider whether it can: + * be featured in a more appropriate place + * grouped with other useful explanations to create a larger topic + * Use asides to call out special cases, or to give more advanced explanations most readers can safely skip + +* **Purposeful Language:** + * **Be consistent:** Use the same terms throughout the article and match the rest of the site–let us know where we got this wrong ourselves\! + * **Define key terms:** Clearly define terms and concepts when you first introduce them. Use bold to highlight the core part of the explanation to aid skimmability. Make sure the bold part reads like a sentence\! + * **Spell out acronyms:** When you introduce an acronym, explain what it stands for. You can choose whether to use: + * **Term (acronym):** if the full term is common or it helps initial understanding (“`A Version Control System (VCS) helps people…`”) + * **Acronym (term):** if the acronym is frequently encountered in the wild (“`NPM (Node Package Manager) is a powerful tool that…`”) + * **Separate Sentences:** if the expansion requires more context or you want to elaborate on its meaning (“`HTML defines the structure of your websites. Its name stands for HyperText Markup Language, highlighting its ability to…`”) + * **Clarify confusion:** explicitly call out terms that are often mixed up (e.g. `terminal program` vs `script` vs `command`) and differences across systems (e.g. `path separators`). When the differences are not important, acknowledge that and, if needed, add further explanations in an aside. + * **Avoid filler words:** Remove words that do not add value or clarity to the sentence. If you can say it in five words, don’t say it in ten. + +# **Content Formatting** + +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 focused on a single idea. + * Be generous with them. + * The key idea should be in the first sentence of each paragraph. Follow up sentences provide additional context/information. + +* Bold: + * Use bold to highlight the key big idea in an article, or other crucial concepts. For highlights, try to capture a whole idea. 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\! As a general rule, highlight the one thing that you’d want the reader to take away from the article after they finish reading it. + * Make sure not to bold too often in a row, as it can get overwhelming and lose effectiveness. If you find yourself with multiple key big ideas, you should consider if they would be better served by being separated into their own article each. This also applies to sections and paragraphs, too. +* Italics: + * Group together longer titles without using “” (e.g. These articles are designed as companions to *FujoGuide Issue 1: Local Version Control with Git*, which you can buy…) + * Stress important points in sentences, e.g. pay *very close* attention to the path you give to the `rm` command. Similar to bold, you should not emphasize every other word in a sentence. If there are multiple important points in a single sentence, consider breaking them up into their unique paragraph to better space them out. + +* DFN + * Use DFN tag 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). + +* 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. \ No newline at end of file From 77fb55fcadfc14a06a18e2e1a2452bcf3ca1fcd1 Mon Sep 17 00:00:00 2001 From: Rie Date: Sun, 15 Feb 2026 03:49:35 +0000 Subject: [PATCH 2/3] Updated Writing Style and Content Formatting --- .../docs/fujowebdev/style-guide/formatting.md | 95 +++++++++---------- .../docs/fujowebdev/style-guide/style.md | 67 +------------ 2 files changed, 48 insertions(+), 114 deletions(-) diff --git a/src/content/docs/fujowebdev/style-guide/formatting.md b/src/content/docs/fujowebdev/style-guide/formatting.md index badbece..d644870 100644 --- a/src/content/docs/fujowebdev/style-guide/formatting.md +++ b/src/content/docs/fujowebdev/style-guide/formatting.md @@ -4,68 +4,67 @@ 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. +# **Content Formatting** -### General Formatting +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. -- **Paragraphs:** Keep them short and (ideally) focused on one idea. Be generous with them\! +### **General Formatting** -- **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\!” +* Paragraphs: + * Keep them short and focused on a single idea. + * Be generous with them. + * The key idea should be in the first sentence of each paragraph. Follow up sentences provide additional context/information. - - 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\! +* Bold: + * Use bold to highlight the key big idea in an article, or other crucial concepts. For highlights, try to capture a whole idea. 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\! As a general rule, highlight the one thing that you’d want the reader to take away from the article after they finish reading it. + * Make sure not to bold too often in a row, as it can get overwhelming and lose effectiveness. If you find yourself with multiple key big ideas, you should consider if they would be better served by being separated into their own article each. This also applies to sections and paragraphs, too. +* Italics: + * Group together longer titles without using “” (e.g. These articles are designed as companions to *FujoGuide Issue 1: Local Version Control with Git*, which you can buy…) + * Stress important points in sentences, e.g. pay *very close* attention to the path you give to the `rm` command. Similar to bold, you should not emphasize every other word in a sentence. If there are multiple important points in a single sentence, consider breaking them up into their unique paragraph to better space them out. - - Make sure not to bold too often in a row, as it can get overwhelming and lose effectiveness. +* DFN + * Use DFN tag 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). -- **Emphasis:** We use _emphasis/italics_ to: +* 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. - - Stress important points in sentences, e.g. pay _very close_ attention to the path you give to the `rm` command. +* 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 - - 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. +### **Code Formatting** - - 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…) +* 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. -- **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: +### **Other Formatting** - - Relevant articles from elsewhere on `learn.fujoweb.dev`, especially for prerequisites, terms definitions, or deeper knowledge +Images: - - Authoritative external sources (e.g. `MDN`, official tool docs) +* 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. - - If we don’t have a guide, we might try to find a good substitute on the web. However, these links tend to rot. +Diagrams: -- **Lists:** Use lists generously, as they help with skimmability. You should: +* [We use Excalidraw for diagrams](https://excalidraw.com/). +* Make sure you download the `.excalidraw` file and not just the PNG. - - Use numbered lists for items in sequence (e.g. we’ll learn 1\) how to do A 2\) how to do B…) +Tabs: - - Use bullet point lists for key takeaways or items not in a sequence (like this list\!) +* 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. - - 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. +**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. \ No newline at end of file diff --git a/src/content/docs/fujowebdev/style-guide/style.md b/src/content/docs/fujowebdev/style-guide/style.md index 19ad4bb..99e7432 100644 --- a/src/content/docs/fujowebdev/style-guide/style.md +++ b/src/content/docs/fujowebdev/style-guide/style.md @@ -102,69 +102,4 @@ The following conventions help us craft effective explanations that are easy to * **Acronym (term):** if the acronym is frequently encountered in the wild (“`NPM (Node Package Manager) is a powerful tool that…`”) * **Separate Sentences:** if the expansion requires more context or you want to elaborate on its meaning (“`HTML defines the structure of your websites. Its name stands for HyperText Markup Language, highlighting its ability to…`”) * **Clarify confusion:** explicitly call out terms that are often mixed up (e.g. `terminal program` vs `script` vs `command`) and differences across systems (e.g. `path separators`). When the differences are not important, acknowledge that and, if needed, add further explanations in an aside. - * **Avoid filler words:** Remove words that do not add value or clarity to the sentence. If you can say it in five words, don’t say it in ten. - -# **Content Formatting** - -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 focused on a single idea. - * Be generous with them. - * The key idea should be in the first sentence of each paragraph. Follow up sentences provide additional context/information. - -* Bold: - * Use bold to highlight the key big idea in an article, or other crucial concepts. For highlights, try to capture a whole idea. 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\! As a general rule, highlight the one thing that you’d want the reader to take away from the article after they finish reading it. - * Make sure not to bold too often in a row, as it can get overwhelming and lose effectiveness. If you find yourself with multiple key big ideas, you should consider if they would be better served by being separated into their own article each. This also applies to sections and paragraphs, too. -* Italics: - * Group together longer titles without using “” (e.g. These articles are designed as companions to *FujoGuide Issue 1: Local Version Control with Git*, which you can buy…) - * Stress important points in sentences, e.g. pay *very close* attention to the path you give to the `rm` command. Similar to bold, you should not emphasize every other word in a sentence. If there are multiple important points in a single sentence, consider breaking them up into their unique paragraph to better space them out. - -* DFN - * Use DFN tag 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). - -* 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. \ No newline at end of file + * **Avoid filler words:** Remove words that do not add value or clarity to the sentence. If you can say it in five words, don’t say it in ten. \ No newline at end of file From cfa96a2e8cbca4ea456077ee4c3cc72794409e6e Mon Sep 17 00:00:00 2001 From: ria <42520601+riazaia@users.noreply.github.com> Date: Thu, 26 Feb 2026 23:03:14 +0000 Subject: [PATCH 3/3] Fix headers --- src/content/docs/fujowebdev/style-guide/formatting.md | 10 ++++------ src/content/docs/fujowebdev/style-guide/structure.md | 2 -- src/content/docs/fujowebdev/style-guide/style.md | 4 +--- 3 files changed, 5 insertions(+), 11 deletions(-) diff --git a/src/content/docs/fujowebdev/style-guide/formatting.md b/src/content/docs/fujowebdev/style-guide/formatting.md index d644870..7970a82 100644 --- a/src/content/docs/fujowebdev/style-guide/formatting.md +++ b/src/content/docs/fujowebdev/style-guide/formatting.md @@ -4,11 +4,9 @@ sidebar: order: 5 --- -# **Content Formatting** - 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** +## **General Formatting** * Paragraphs: * Keep them short and focused on a single idea. @@ -40,7 +38,7 @@ Our content is designed for *skimmability*: as you write it, imagine you’re on * 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** +## **Code Formatting** * Inline Code: We use inline code to highlight: * Commands (e.g. `git commit -m “your message”`) @@ -50,7 +48,7 @@ Our content is designed for *skimmability*: as you write it, imagine you’re on * 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** +## **Other Formatting** Images: @@ -67,4 +65,4 @@ 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. \ No newline at end of file +**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. diff --git a/src/content/docs/fujowebdev/style-guide/structure.md b/src/content/docs/fujowebdev/style-guide/structure.md index 553852b..5bd8286 100644 --- a/src/content/docs/fujowebdev/style-guide/structure.md +++ b/src/content/docs/fujowebdev/style-guide/structure.md @@ -4,8 +4,6 @@ sidebar: order: 3 --- -# **Article Guidelines** - ## **Article Function** All articles should follow three key principles: diff --git a/src/content/docs/fujowebdev/style-guide/style.md b/src/content/docs/fujowebdev/style-guide/style.md index 99e7432..e677611 100644 --- a/src/content/docs/fujowebdev/style-guide/style.md +++ b/src/content/docs/fujowebdev/style-guide/style.md @@ -4,8 +4,6 @@ sidebar: order: 4 --- -# **Writing Style** - This guide is here to create a consistent style our readers can come to trust and learn from. At all times, we must balance technical knowledge with the casual, friendly banter of hobby spaces. When writing for FujoGuide, **think of yourself as a knowledgeable friend**, rather than a formal instructor. You are deeply invested in the reader’s success, have a strong belief in their abilities, and yet relate to their present struggles—you too have been an *intimidated beginner* once\! @@ -102,4 +100,4 @@ The following conventions help us craft effective explanations that are easy to * **Acronym (term):** if the acronym is frequently encountered in the wild (“`NPM (Node Package Manager) is a powerful tool that…`”) * **Separate Sentences:** if the expansion requires more context or you want to elaborate on its meaning (“`HTML defines the structure of your websites. Its name stands for HyperText Markup Language, highlighting its ability to…`”) * **Clarify confusion:** explicitly call out terms that are often mixed up (e.g. `terminal program` vs `script` vs `command`) and differences across systems (e.g. `path separators`). When the differences are not important, acknowledge that and, if needed, add further explanations in an aside. - * **Avoid filler words:** Remove words that do not add value or clarity to the sentence. If you can say it in five words, don’t say it in ten. \ No newline at end of file + * **Avoid filler words:** Remove words that do not add value or clarity to the sentence. If you can say it in five words, don’t say it in ten.