Skip to main content

How we write guides

No experience necessary. Questions encouraged.

Northern Michigan Mesh exists to teach the reasoning behind technology, not hand out unexplained settings that only work on one person's network.

What every guide should do​

  1. Begin with the actual question. What is the reader trying to understand or accomplish?
  2. Say what the reader needs first. Previous knowledge, tools, safety precautions and applicable licensing considerations should never be hidden assumptions.
  3. Define terms before using them. Write “frequency (how often a radio wave repeats)” before using unexplained abbreviations.
  4. Explain what, why and how. A recommended setting is only useful when the reader understands what it changes and what the alternatives are.
  5. Show what success looks like. Use examples, clear steps, illustrations and expected observations.
  6. Explain failure without blame. Include common mistakes, troubleshooting, and how to back out of a change.
  7. Label facts, assumptions and opinions. A personal setup is not a universal requirement. A community convention is not a regulation.
  8. Welcome correction. Readers can challenge our explanations, even when the author is an administrator.
  9. Respect independence and privacy. Never require people to join a particular server or reveal a location just to learn.
  10. Link primary sources. Where an official manual, specification or government rule applies, let people verify our explanation.

Our typical guide layout​

The question → In one paragraph → Terms explained → Why it works → Step-by-step example → Common mistakes → What to try next → Original sources → Discuss or suggest a correction.

Some guides will be short. Others will go into engineering-level detail. Both are welcome as long as the beginner-friendly explanation remains easy to find.

Make unfamiliar words explain themselves​

Readers should not have to leave an article just to understand a technical term. When a lesson introduces terms such as ground plane, isotropic radiator, SWR, or MeshCore region scope, use our inline explanation feature wherever it genuinely helps.

Our authoring checklist:

  1. Add a plain-English definition to src/data/glossary.json first. That glossary is the single source for popup explanations and searchable definitions.
  2. Introduce the term naturally in the article. For technical terms, use the shared Term component with an appropriate name and visible label.
  3. Choose important first occurrences. Avoid a page where every repetition or ordinary word has a question-mark button; readability still matters.
  4. Support every input method. A visitor should be able to hover, click, tap or use a keyboard to open an explanation. Test both desktop and mobile layouts.
  5. Provide a path to deeper study. Every popup links to its glossary entry; longer explanations belong in the relevant lesson.
  6. Don't treat a quick definition as the full explanation. The article should still explain the why and how.

For authors editing a Docusaurus lesson, use this pattern:

import Term from '@site/src/components/Term';

A <Term name="ground plane" /> provides the RF return structure
used by certain antenna designs.

Gain in dBi is referenced to an <Term name="isotropic radiator" />.

This is a site-wide writing principle, not a feature limited to antenna articles. MeshCore, Meshtastic, APRS, GMRS, packet radio and general RF lessons should all use the same glossary-backed explanations.

Contributions are invited, not demanded​

You can propose a better explanation, offer a diagram, describe a build or point out an error. We'll review contributions for clarity, technical accuracy, safety and respect—not for agreement with an administrator's personal preferences.

The community forum is a place to discuss experiences and suggest improvements. Published tutorials remain available to read without an account.

Curiosity over conformity. Collaboration over control. Community over ego.