User:Aeric/Wiki Versions and Task Processing

The existence of multiple products, multiple versions of those products (cloud and installable), multiple releases, and a Wiki for each combination of product-version of them creates a need to strategize the processing of documentation tasks. This article provides an overview of the Wiki space and outlines those strategies.

This diagram summarizes the information:

File:ProductsAndVersions.png

The Wiki Space

Products

The basic products are AgileApps, focused on case management, and LongJump -- it's historical predecessor. Many features overlap between those two, and sometimes new features apply to both. But many features are unique to AgileApps, including:

• Case Management
• Communication Channels (including social media)
• Overhauled GUI
• Multi-lingual, Accessible interface with localization features

Note: AgileApps has a different interface. So even when the page that provides that functionality is the same, the "how to get here" paths that are part of the procedural steps found in the "Working with" sections will be different.

Versions

There are two versions of each product, the cloud version and the installable version:

• The Wiki that corresponds to the cloud version is updated every 2 or three weeks with new features.
• The Wiki that corresponds to the installable version is a snapshot of the cloud wiki taken a little before or after the installable release.

The cloud version is always accessed using a "/wiki" URL:

• agileappslive.info/wiki for AgileApps
• platformatyourservice.com/wiki for LongJump.

Installable versions are accessed using an identifier and a version number in place of "/wiki".
For example: /lj90 or /aal10.

Releases

Release numbers aren't of much use in the cloud, so cloud releases have dates. Those dates are shown in the Release Notes page in the Wiki. For example: 13 Jan 2014.

For the installable versions, on the other hand, release numbers are more valuable. So an installable release is given a number. That release encompasses all of the dated updates from the last installable release up to the current release date.

The Release Notes for a new instance of the installable version contain:

• Items that are specific to the installable instance (for example, the ability to add MIME types)
• Important things to do for new installations and upgrades
• The collection of applicable new features from the cloud-version release notes.

__TBD:
We need to find a way to add a "water mark" to the release notes when an installable version is released.
That will make it easier to identify the features that need to be called out for Installable Version Release Notes.
We could:

• Point to the cloud version and tell the installer which dates are relevant.
• Have features for each date in its own page and transclude the appropriate dates
• or (easiest) start a new Release Notes page whenever an installable version is released.__

Strategies for Documentation Tasks

These stragegies are the best we have come up with, so far.

Critical Fixes

...

"Cosmetic" Improvements

...

New Features

...

The Fundamental Replication Problem

Over time, it was originally expected that the need to update LongJump documentation would evaporate. But that doesn't seem to be happening. True, only a fraction of the new features affect LongJump. But some of the most critical infrastructure improvements we make generally do.

In the AgileApps wiki, we have development version (mw_dev) and a production version (mw_prod). That strategy allows us to document features for an upcoming cloud release without affecting existing users. A publish script is used to replace the production version with the development version when a release occurs.

We don't particularly want a development version of the LJ wiki, because then there is an additional wiki to manage (6 in all). But since we don't have that: a) The LJ wiki does not reflect changes as they occur in the cloud, and b) Those changes need to be copied to the LJ wiki when a major release occurs.

Our current solution is to add rel notes entries to the Coming Soon section to act as reminders, and then copy the doc pages at release time. But while a release note generally links to a only single page, there is more to consider to replicate all of the changes associated with a new feature:

• Related Pages

Related pages are those that change, as a result of the new feature.

For LDAP integration, for example, the behavior of User Settings changes for admins and users when LDAP is enabled. The changes to those pages need to be migrated, as well. (As long as those sections contain links, they can be found by examining What Links Here. If they don't contain links, the changes will probably be overlooked--which means that every related change must have a link to the feature that prompted the change.)

• Transcluded pages

If a constellation of new features shares some common information that is kept separately, the common-info pages need to be copied as well, or the transclusion-references will fail when the pages are copied for the LJ release.

• Restructured pages

Sometimes a new feature needs to include parts of other descriptions. That generally occurs when a new "feature"

represents a change to existing behavior, rather than some new, independent behavior.

In that case, the restructuring needs to be replicated in the LJ wiki. Otherwise, the transclusion references will fail for them, as well.