Editionwell for Confluence: documentation

Editionwell turns a Confluence page tree into versioned documentation. Each version (2.0, 3.0...) is an ordinary page tree, in a space of its own or next to the others with a title suffix. Editionwell remembers which page is which in every version, gives readers a version switcher, carries changes between versions, and handles variants such as Cloud and Data Center.

Where to find it

• Versions in a space's sidebar (Apps): documentation sets in this space, their versions, the Compare overview, Variants, Latest links and Activity.
• Versions (Editionwell) in a page's "..." menu: this page in every version, compare and carry changes, add the page to another version, link a page copied by hand, and make a latest link.
• The version banner at the top of every page of a versioned set.
• Macros: Variant section (Editionwell) and Variant text (Editionwell) in the editor's / menu.

Set up

1. Open Versions in the sidebar of the space that holds your documentation.
2. Name the documentation (for example "Acme Server Admin Guide"), pick its root page (the page at the top of the tree, or the space homepage), and name this version (for example "2.0").
3. If the pages of this version already end with a version suffix such as " (2.0)", enter it, so Editionwell can tell "Install (2.0)" and "Install (3.0)" are the same page.
4. Press Create documentation set. The tree is version 2.0, current and latest. Every page under the root belongs to it, including pages added later.

Already have older versions copied by hand? Use Add a tree that already exists as a version in the Versions tab. Pages are matched by title (without the suffix); fix any odd match from the page's Versions panel.

Start a new version

In the Versions tab, under Start a new version:

• Copy from: usually the latest version.
• New version name: for example "3.0".
• Where: in a space of its own (recommended: titles stay the same, so links and search read naturally; create an empty space first) or in the same space (Confluence titles are unique per space, so every page of the new version gets a title suffix such as " (3.0)").

Editionwell copies every page in tree order, with labels and attachments, and points links between pages of the documentation at the new copies. Links to pages outside the documentation keep pointing at the original pages; the job report lists them. The new version starts as a draft: writers can work on it while readers don't see it in the switcher. Press Publish to readers when it is ready, or Make latest to make it the version readers are sent to.

The version banner

On every page of a set, readers see the documentation name, the version they are reading and a Version picker that opens the same page in any other version (or that version's start page when the page doesn't exist there). On older versions the banner says which version is latest and offers Read this page in 3.0. Archived versions are marked; draft versions only show to people reading the draft. You can hide the banner on pages of the latest version in the Variants tab.

Compare and carry changes

One page, change by change. Open a page's "..." menu > Versions (Editionwell) > Compare. Pick the other version and the direction:

• Take this page's changes to 3.0 writes into the 3.0 page;
• Bring 3.0's changes into this page writes into the page you are on.

Editionwell lists every changed paragraph, heading, table or macro as a separate change, with "-" lines for what the target says now and "+" lines for what it will say. Links to pages of the documentation are translated to the target version first, so they never show up as changes. Tick the changes you want and press Write. The page gets one new version; if someone saved it while you were comparing, Editionwell refuses and asks you to compare again.

Many pages at once. In the Compare tab press Compare versions now. The table shows every page in every version: Same (as the nearest earlier version that has it), Changed, Added (first version that has it) and Not here. Turn on "Only pages that differ from the latest version" to focus. Tick pages, choose From and To, and Carry: each ticked page is written over its counterpart (or created there, under the counterpart of its parent).

Pages copied by hand or renamed. In the page's Versions panel, Link a page that was copied by hand with the other page's link. Add to 3.0 creates the page in a version that lacks it.

Variants

In the Variants tab, list your variants, one per line (for example Cloud and Data Center), and choose the variant readers get before they pick one (or none, to show everything).

• Variant section (Editionwell): insert it, type the variant-specific content inside it, and in its settings list the variants (comma separated) and choose Only readers of these variants or Everyone except readers of these variants. Readers of other variants don't see the section.
• Whole pages: add the label shown in the Variants tab (for example variant-data-center) to a page that only applies to that variant. The banner tells readers of other variants, and variant publishing leaves the page out.
• Variant text (Editionwell): define variables in the Variants tab (for example product = "Acme Cloud" for Cloud and "Acme Server" for Data Center) and insert the macro where the word should appear.

Readers pick their variant in the banner (All variants shows every section with a small label). PDF and Word exports follow the exporting person's variant.

Publish a variant. Choose a version, a variant and an empty space of its own, then Publish. Editionwell writes the version as that variant: sections for other variants removed, Variant text filled in, pages labelled for other variants left out, and no Editionwell macros left. Search, PDF/Word export and anonymous sharing of that space show exactly that variant. Publish again after changes: changed pages are updated, pages that left the variant are moved to the trash.

Limits: a Variant section can't hold another bodied app macro (Confluence's own rule for bodied macros). Page titles are not variant-specific.

Latest links

Links to a version go stale when the next one ships. An alias page always opens the latest version: create one for the whole documentation in the Latest links tab, or for one page from its Versions panel. Put alias pages outside the version trees (for example in a links space). Link to them from Jira, emails and other spaces. Stop redirecting keeps the page but ends the redirect.

Archive and remove

• Archive marks a version archived: the banner says so and points to the latest version. Tick Also move its pages to Confluence's archive to make them read-only and take them out of search and the page tree (needs the Archive permission, and a Confluence plan that allows archiving through the API; otherwise Editionwell tells you and you can archive from Confluence's menu). Unarchive sets the version back to current (pages in Confluence's archive are restored from Confluence's Archived pages).
• Remove from set forgets a version; its pages stay where they are.
• Delete documentation set forgets the set, its mapping, variants and alias redirects. No page is deleted.

Permissions

• Anyone who can see a page sees its banner and counterparts.
• Creating a set and adding a page to a version: permission to add pages in that space.
• Starting a version, carrying pages and publishing a variant: permission to add pages in the target space. The work runs in the background as the app, so the app also needs to be allowed to add pages there.
• Managing a set (latest, statuses, archive, variants, removal): the person who set it up, or an admin of its space.
• Carrying changes into a single page runs as you: you need to be able to edit that page.

Subscription

Creating sets and versions, carrying changes, publishing variants and alias pages need an active subscription. Without one, your pages stay ordinary Confluence pages, the banner is hidden, variant sections show to everyone, and archiving and the activity log still work.

Data

Editionwell runs on Atlassian's Forge platform and stores its data (the mapping between versions, variants, readers' variant choices, jobs and the activity log) in your site's Forge storage. No page text is stored and nothing leaves Atlassian. See the privacy policy: https://greatwork.company/apps/editionwell/privacy.