Editorial policy

Illustration for Editorial Policy documentation

Summary

LeMaker documentation follows a consistent editorial approach designed to maximize practical usefulness while maintaining technical accuracy. Every page prioritizes verifiable procedures over theoretical discussions, explicit assumptions over implied knowledge, and stable internal references over external dependencies. This editorial policy defines our writing standards, content structure requirements, terminology choices, and quality criteria that ensure documentation serves its primary purpose: helping users accomplish specific tasks with LeMaker hardware.

These standards apply to all technical documentation pages across the main site, resource sections, and wiki content. Contributors and maintainers use this policy as the authoritative reference for content decisions.

Core editorial principles

Explicitness over assumptions

  • Name specific hardware - Always identify exact board model (Banana Pi, Banana Pro, HiKey, HiKey 960) rather than generic "the board"
  • Specify OS images precisely - Include complete filename, version, and download source rather than "latest image"
  • State storage requirements - Mention microSD card class, capacity, and brand recommendations explicitly
  • Document power requirements - Specify voltage, current rating, and cable considerations for each procedure
  • Define prerequisites - List required hardware, software, and knowledge before procedural steps

Verifiable procedures over descriptions

  • Provide concrete commands - Include copy-paste ready terminal commands with expected output
  • Show validation steps - Explain how to confirm each step succeeded before proceeding
  • Include failure modes - Document what goes wrong and how to recognize problems
  • Use checklists - Break complex procedures into numbered steps users can mark off
  • Demonstrate with examples - Show actual command output, log excerpts, and configuration files

Stability and longevity

  • Maintain stable URLs - Never rename or move pages; existing links must continue working
  • Prefer internal links - Link to LeMaker documentation first; external references only when necessary
  • Archive historical content - Keep documentation for older boards and images accessible
  • Date all updates - Include "Last updated" timestamps on every page
  • Version-tag procedures - Note when instructions apply to specific kernel or OS versions

Required content structure

Every technical documentation page must include these sections in order:

1. Summary (required)

Two to four sentences answering: What does this page cover? Who needs this information? When would you use this procedure?

2. Prerequisites (required for procedures)

Explicit list of required items:

  • Hardware components (boards, cables, storage media)
  • Software dependencies (installed packages, host OS requirements)
  • Prior knowledge (assumed skills, prerequisite reading)
  • Time estimates (how long the procedure typically takes)

3. Step-by-step procedure (required for how-to pages)

Numbered steps with:

  • Action to perform (imperative voice: "Run this command", "Connect this cable")
  • Expected result (what success looks like)
  • Validation check (command or observation to confirm success)
  • Recovery guidance (what to do if this step fails)

4. Concrete example (required)

At least one real command, configuration file excerpt, or log sample demonstrating the concept. Use <pre><code> blocks with syntax highlighting when appropriate.

5. Troubleshooting (required)

Common problems users encounter, structured as:

  • Symptom - Observable behavior (error message, LED pattern, missing output)
  • Probable cause - Most likely explanation for this symptom
  • Fix - Specific corrective action with commands or configuration changes

6. FAQ (recommended)

Six to twelve frequently asked questions with concise answers. Focus on questions users actually ask in forums and support channels.

7. Related guides (required)

Internal links to:

  • Prerequisite procedures (what to do before this)
  • Next-step procedures (what to do after this)
  • Related specifications or references
  • Troubleshooting resources

Language and style standards

UK English conventions

  • Use UK spelling: "colour" not "color", "organisation" not "organization"
  • Exception: Technical terms and commands remain standard ("systemctl", not "systemct1")
  • Exception: Quoted text from external sources preserves original spelling

Voice and tone

  • Active voice preferred - "Run the command" instead of "The command should be run"
  • Imperative for instructions - "Connect Ethernet cable" not "You should connect"
  • Direct and concise - Eliminate unnecessary words; respect reader's time
  • Honest about limitations - Acknowledge when procedures vary by configuration
  • Neutral technical tone - Avoid marketing language, hype, or emotional appeals

Forbidden terminology

Never use these terms in documentation:

  • "Rebuild", "archived", "archive" (when referring to site purpose)
  • "Link equity", "authority flow", "expired domain"
  • "SEO juice", "salvage", "capture backlinks"
  • "Obviously", "simply", "just" (minimize reader assumptions)

Use neutral alternatives:

  • "Documentation continuity" instead of "archive"
  • "Stable references" instead of "link equity"
  • "Historical URLs" instead of "expired domain"
  • "Long-term page location" instead of "permanent redirect"

Technical accuracy requirements

Command examples

  • Test all commands on actual hardware before publishing
  • Include full output when illustrative; truncate with "[...]" when necessary
  • Note which user account commands require (root, normal user, specific permissions)
  • Specify working directory when path-sensitive
  • Escape special characters appropriately for shell context

Version specificity

  • Tag kernel-specific procedures with version numbers
  • Note when commands differ between distributions
  • Indicate deprecated procedures with warnings and alternatives
  • Update date stamps when procedures change

Hardware specifications

  • Cite manufacturer documentation for electrical specifications
  • Note when specifications vary by board revision
  • Include practical observations ("typically draws 800mA under load")
  • Warn about common hardware issues (poor microSD cards, inadequate power)

Linking guidelines

Internal links (preferred)

  • Link to other LeMaker documentation whenever relevant context exists
  • Use descriptive link text ("Banana Pi specifications" not "click here")
  • Verify links work before publishing
  • Use relative URLs for internal links when possible

External links (use sparingly)

  • Link to authoritative sources: kernel.org, manufacturer datasheets, standards bodies
  • Avoid linking to forums, blog posts, or volatile content
  • Include context: "(manufacturer datasheet)" or "(kernel documentation)"
  • Note when external links are reference-only vs. required reading

Content maintenance procedures

Regular review cycle

  • Core procedure pages: Review quarterly
  • Specification pages: Review annually or when hardware updates
  • Troubleshooting pages: Update based on community reports
  • Download pages: Verify links monthly

Update process

  • Test updated procedures on hardware before publishing
  • Change "Last updated" date stamp
  • Note significant changes in git commit messages
  • Preserve old content when procedures change (historical reference value)

Frequently asked questions

Why UK English specifically?

Consistency matters more than dialect choice. We selected UK English and maintain it uniformly. Technical terms, commands, and code remain standard across all English variants.

Can I use screenshots instead of text examples?

Text examples are searchable, copy-pasteable, accessible to screen readers, and never become outdated due to UI changes. Use screenshots only when visual identification is essential (LED locations, connector types).

What if a procedure doesn't work on my specific setup?

Document scope boundaries explicitly. Note tested configurations. When procedures vary, provide decision trees or conditional steps rather than claiming universal applicability.

How detailed should troubleshooting sections be?

Cover the three most common failure modes for each procedure. Link to comprehensive troubleshooting pages rather than duplicating extensive diagnostics on every page.

Should I include theoretical background information?

Include minimum necessary context for users to understand why they're performing steps. Link to external resources for deep theoretical discussion. Prioritize practical application over academic completeness.

What makes a good concrete example?

Show actual command output, not sanitized or idealized versions. Include timestamps, realistic hostnames (anonymized if needed), and typical error messages users might encounter.

How do I handle deprecated procedures?

Add prominent warning at top of page noting deprecation, explain why, and link to current recommended procedure. Keep deprecated content accessible for historical systems.

Quality checklist before publishing

  • ? Summary clearly states page purpose and audience
  • ? Prerequisites list all required hardware, software, and knowledge
  • ? Procedures use numbered steps with validation checks
  • ? At least one concrete command or configuration example included
  • ? Troubleshooting covers three most common failure modes
  • ? Related guides link to prerequisite and next-step procedures
  • ? All commands tested on actual hardware
  • ? No forbidden terminology used
  • ? Internal links verified working
  • ? "Last updated" date stamp current
  • ? Page meets 1000+ word minimum for substantive content

Author: LeMaker Documentation Team
Last updated: 2026-01-10