Community Edition Design Criteria
=================================

A list of properties we want every community edition to have.  Drawn from
discussion in the [TiddlyTalk threads][t1] [(2)][t2] [(3)][t3] [(4)][t4] and
refined here.  Ordered roughly from most to least important — when principles
conflict, the earlier one usually wins.


Criteria
--------

An edition:

  - **must serve a useful and relatively common purpose.**  The test is whether
    a stranger would immediately recognize the need ("oh, I've wanted that").
    Someone's wiki exploring entomological appearances in 20th century
    literature may be fascinating, but is not going to be reused by very many
    people.

  - **should have a clear, narrow scope** and resist feature creep.  It is
    better to do one thing well and keep a "futures" list than to grow into a
    sprawling tool.

  - **should work out of the box** without the user needing to configure
    anything before it is useful — good defaults, sensible structure, ready to
    populate.

  - **should be self-documenting from within.**  A tiddler (or small set)
    explaining the conventions used, what the key tiddlers do, and how to extend
    or customize.

  - **should ship with illustrative sample content.**  Enough to show what a
    real, populated version looks like, without being so specific that users
    feel they must delete everything before starting.  Ideally, this is just
    a JSON bundle that can be added to an empty version, so that there are two
    artifacts delivered: a complete empty edition and the JSON sample content.

  - **should have a complexity ceiling.**  A motivated new user should be able
    to understand the whole edition in a single sitting — roughly 1,000 words of
    explanation should suffice.

  - **should make common customizations easy.**  Theming via the palette;
    user-facing text in a small set of well-named tiddlers rather than scattered
    hardcoded strings; sensible structure for adding fields or tags.  It should
    remain localization-friendly:  No hardcoded UI strings or colors; structure
    clean enough that someone could translate without surgery.

  - **should showcase idiomatic TiddlyWiki.**  While it is primarily functional,
    it should also be educational — demonstrating patterns a new user could
    learn from and adapt.

  - **should be maintainable.**  Prefer core TW mechanisms and established
    community plugins over custom wikitext, so fewer things break when TW itself
    updates.

  - **should follow TW namespace conventions.**  Edition-specific tiddlers under
    a logical prefix (e.g. `$:/community/recipes/`); palette colors instead of
    hardcoded CSS values.

  - **should prefer modern TW techniques and tools, but should not go out of its
    way to promote them.**  For instance, choose `<% if %>` over a `<$list>` or
    `<$reveal>` used for the same purpose.

  - **should be deployment-agnostic** where practical: single-file HTML
    for simplicity, but nothing that would break in a Node.js or server
    deployment.


Decisions
---------

  - **Documentation lives inside each artifact.**  Both the empty edition and
    every companion content collection carry the documentation needed to use
    them.  The exact mechanism (where docs live, how they're structured, how
    they survive content changes) will be worked out during the building of the
    recipe edition.

  - **Empty edition plus one or more content collections.**  Every edition ships
    as an empty version plus one or more companion JSON content collections that
    can be loaded into it to produce a populated variant.  A single edition may
    reasonably ship multiple collections covering different locales, styles, or
    subdomains — for the recipe edition, a US-customary sample and a metric
    sample are an obvious first pair.  Later l10n and i18n work may multiply the
    collections further.

    Any populated variant must carry a method to delete all demonstration
    content cleanly, resetting to the empty edition plus the user's own
    additions.

  - **Full i18n is not a primary concern.** Internationalization (RTL,
    locale-sensitive number/date formatting, plural rules) is a separate concern
    that may apply to specific editions (recipes, for example) but is not a
    baseline requirement.

  - **Critical dependencies are bundled.**  Anything required for the edition to
    function as we intend to present it ships inside the edition file.  To
    compensate for the version-pinning that bundling implies, the edition will
    integrate a "phone home" check against the editions tool that reports
    compatibility-tested updates of bundled plugins, e.g.:

      - In the wiki: *"Relink 3.2.1 has been found compatible with this wiki.
        You're on 2.7.8.  Do you want to update?"*
      - In the editions tool: *"This edition has been tested on TW 5.3.7, 5.3.8,
        and 5.4.0.  Every version of Relink from 1.2.3 through 3.2.1 has worked
        fine except for 2.2.2..."*

    Extended-functionality plugins (e.g. *"install SuperSearch 8.9.10 for these
    benefits"*) are interesting but deferred — first build an edition or two,
    then return to extensibility.



  [t1]: https://talk.tiddlywiki.org/t/8593
  [t2]: https://talk.tiddlywiki.org/t/8618
  [t3]: https://talk.tiddlywiki.org/t/8742
  [t4]: https://talk.tiddlywiki.org/t/8743
