Article Writing Guide

The course should read like a collection of thoughtful technical articles, not a workbook assembled from a fixed lesson template. Each article should explain a coherent topic in enough depth that an experienced programmer can form a useful mental model and then recognize the concept in real code.

This guide describes a shared style, not a required outline. Authors should use whatever structure best serves the subject.

What an article should feel like

An article should:

• Begin from a concrete question, problem, or piece of code.
• Explain the concept as a connected narrative.
• Include examples directly in the Markdown where they become relevant.
• Spend more time on semantics and judgment than on cataloging syntax.
• Assume general programming competence.
• Explain JavaScript and TypeScript directly rather than translating every idea from another language.
• Call out surprising behavior when a reader's existing intuition is likely to be wrong.
• Finish when the topic has been explained; it does not need to fill a standard set of sections.

An article should not be required to contain objectives, prerequisites, a mental-model heading, prediction exercises, guided practice, a checklist, a retrospective, or external example files. Those devices may occasionally be useful, but they should not define the course's rhythm.

A loose shape

Many articles will naturally follow a shape like this:

1. Introduce a real situation or representative snippet.
2. Explain the basic syntax while following what the program does.
3. Develop the underlying runtime or type-system model.
4. Explore important variations and edge cases.
5. Discuss conventions and design choices found in real codebases.
6. Connect the topic to later parts of the ecosystem when useful.
7. End with a concise synthesis or a few questions worth keeping in mind.

This is not a table of contents that must be copied into every article. A short article about template literals may have three headings. An article about closures or the event loop may have a dozen.

Embedded examples

Examples should live inside the prose:

const preferences = {
  volume: 0,
};

const volume = preferences.volume ?? 5;
console.log(volume); // 0

The explanation should immediately say why the example matters:

?? falls back only for null and undefined, so the valid value 0 survives. Using || here would replace it with 5 because 0 is falsy.

Prefer examples that are:

• Small enough to understand without opening another file.
• Complete enough to show the relevant types and values.
• Realistic enough to resemble production code.
• Explicit about their output when the result is not obvious.
• Focused on one main idea at a time.

There is no need to create a separate .js file for every snippet. A larger example may grow across several snippets in the article, but each stage should remain readable in context.

Explanation depth

The target reader can already program. Articles do not need to explain what a variable, loop, function, class, or generic is from first principles. They do need to explain what is distinctive about the JavaScript or TypeScript version.

For example, an article about functions can move quickly through declaration syntax and spend more time on:

• Functions as ordinary values.
• Differences between declarations, expressions, and arrows.
• Lexical capture.
• How invocation determines this for ordinary functions.
• Why callback-heavy APIs shape common JavaScript design.

Likewise, a TypeScript article should not merely list annotation syntax. It should explain structural compatibility, inference, narrowing, erasure, and the boundary between static claims and runtime data.

Prior-language comparisons

Experience with Swift, Java, C#, and Python is background context, not a recurring article format. Do not add a comparison section by default.

Use a comparison only when an unusual behavior is likely to conflict with intuition developed in one or more of those languages. Keep all relevant languages in one brief discussion. Examples where this may help include:

• const prevents rebinding but does not make an object immutable.
• JavaScript objects compare by identity rather than structural contents.
• A regular function's this depends on how it is called.
• JavaScript classes are built on prototype delegation.
• Promises are not Swift structured-concurrency tasks.
• TypeScript is structurally typed and its types are erased.

If the idea is straightforward, explain it without a comparison.

Syntax coverage

Syntax should be introduced through useful code rather than a detached catalog. Still, the collection of articles must eventually cover the everyday syntax listed in the curriculum.

When an article introduces syntax:

• Show the ordinary modern form first.
• Explain older forms when readers will encounter them in existing code.
• Distinguish language rules from conventions.
• Point out whether a construct mutates data or produces a new value.
• Include edge cases only when they affect normal engineering decisions.

Avoid turning every operator or method into its own article. Group features around a coherent programming activity, such as transforming collections or defining a module API.

Conventions and judgment

The course should teach how JavaScript and TypeScript are commonly written, while being honest about alternatives.

Useful distinctions include:

• What the language requires.
• What most modern codebases conventionally do.
• What is merely the course's chosen default.
• When an alternative approach is clearer.

For example, const by default is a strong convention. Using map instead of a loop is not inherently better; the choice depends on whether the operation is a transformation and which version communicates the intent more clearly.

Article endings

An article does not need a quiz or completion checklist. It should usually end with one of:

• A short synthesis of the mental model.
• A comparison of the design choices just discussed.
• A small set of questions the reader should now be able to answer.
• A transition explaining why the next article follows naturally.

Avoid repetitive “in this lesson you learned” sections unless they genuinely help summarize a complex topic.

Integrated case studies

The course does not contain assignments or exercise projects. When several concepts benefit from being seen together, develop a case study inside the article itself. A data-validation pipeline, module boundary, concurrent worker, or browser interface can grow through several embedded snippets while the prose explains each design decision.

The case study should remain subordinate to the article's explanation. It does not need starter files, acceptance criteria, hidden tests, or a reader deliverable.

Suggested article sizes

Length should follow the subject, but these ranges are useful:

Article kind	Approximate length
Focused syntax or convention	1,000–1,800 words
Core language semantics	1,800–3,500 words
Runtime, modules, or async model	2,000–4,000 words
TypeScript modeling topic	2,000–4,000 words
Browser or framework architecture	2,000–4,500 words

Split an article when it develops two independent mental models, not merely because it has become long.

Author review

Before considering an article complete, check that:

• The narrative has one coherent purpose.
• Important claims are accurate for the declared environment.
• Examples are syntactically and semantically correct.
• Output comments match actual behavior.
• New terminology is explained near its first use.
• General programming basics are not overexplained.
• Surprising JavaScript or TypeScript behavior receives enough explanation.
• Prior-language comparisons appear only where they prevent a likely misconception.
• Language features, host APIs, and framework APIs are clearly distinguished.
• The article does not contain artificial exercises, assignments, or headings added only to satisfy a template.
• The ending leaves the reader with a useful mental model or transition.

Example of an appropriate opening

An article about nullish values might open this way:

Configuration code often has to distinguish between a missing value and a deliberately empty one. This looks harmless:

const retryCount = options.retryCount || 3;

But a caller that explicitly requests zero retries receives three. The bug comes from using JavaScript's truthiness rules to answer a more precise question: whether a value is absent.

From there, the article can naturally introduce falsy values, ||, ??, optional chaining, explicit validation, and conventions for boundary code without placing each idea into a standardized lesson section.