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.

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:

• agileappscloud.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.

Note: For AgileApps, there are actually two versions of the cloud wiki: The development version for upcoming features, and the production version for currently released features.

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
• Start a new Release Notes page whenever an installable version is released.

(The last option is probably the best. At the top of the page, we can add a link to a previous-version index page. At release time, the Release Notes page gets a title that includes the version number. That page then remains the Release Notes page until the next cloud release.

Strategies for Documentation Tasks

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

Task Categories

One mechanism that helps to keep track of priorities involves the nature of the task, because the categories as a whole tend to take on a higher or lower priority, depending on where we are in a release cycle or sales cycle. (Does a prospect need an article? Is a cloud release coming up? An installable release? Whichever it is raises the priority of that category or group to the highest level.)

• User/Designer

Documentation that affects the user experience and the designer's experience take the highest priority, as they are generally tied to important features.

• Article

Articles like How to Create an Application and the much-needed (but not yet written) How Lookups Work are critical to engender understanding and acceptance.

In practice, their priority tends to be non-existent until they're needed. Then they become the highest priority there is. But after an initial version is published, it can be difficult to find time for fixes and improvements. (That has certainly been the case with the first one, which needs an overhaul.

• API/Developer

Docs for API enhancements and coding take a second seat these days, because most things are accomplished by configuring Web Services, Rules, and Processes. So coding is not as important as it once was. (But when needed, it is still very important.)

• Code Sample

Code samples are useful templates that developers can use.

• Installation

Documentation tasks for the installable version tend to be put on the back burners until an installable release draws near.

Task Types

• Critical Fixes

These are necessary corrections or additions, without which a feature is unusable, and which are likely to be needed by others.

The need for a fix comes to light generally as a result of a customer query. If they're asking about a feature that is likely to be used by others, the fix becomes critical. It is then made to the appropriate product/version wikis.

If it's a little-used feature, then they are given the information they need by support or by developers. The doc changes are then relegated to something closer to "cosmetic" status. The changes are made to the next version of the wiki, and auto-updated when the time comes.

__TBD: That works fine for AgileApps. We make the change to the dev wiki, and it becomes part of the production wiki the next time the dev wiki is published. But we have no way to track those changes for LongJump. So they may never appear in the LongJump wiki.__

• "Cosmetic" Improvements

A cosmetic improvement is one that makes the documentation easier to read or to use. It may include reorganization of pages, restructuring of content, simple wordsmithing, or all of the above.

All such work is confined to the AgileApps development wiki. When published, it becomes part of the production wiki. For sheer lack of manpower, those cosmetic changes are never introduced to the LJ wiki.

__TBD: Another gray area occurs when pages are restructured to make things more readable and maintainable. At some point, some feature page links to or transcludes one of the newly re-structured pages that does not exist in the LJ wiki. When the page is copied, the link or transclusion fails. To solve the problem, one could simply copy in the new page--but then there are two copies of the information in the LJ wiki--and that page could differ from the existing material, now or in the future. The only alternative is to replicate the restructuring that took place in the original wiki--at a time when many of the details and motivations are no longer fresh in one's mind.__

• New Features

For new features, there are several steps:

• For an AgileApps feature, an entry is added the Release Notes in the dev wiki

That entry contains a link to the documentation page, which is also added to the dev wiki

• That entry is copied to the Coming Soon section of the production wiki, minus the link and the documentation page.
• If the feature also applies to LongJump, an entry is added to the Coming Soon section of the LJ wiki, to serve as a reminder that the documentation needs to be copied, and the link added to the rel note.

(New features are not added to LongJump unless they also apply to AgileApps.)

The Fundamental Replication Problem

Over time, it was originally expected that the need to update LongJump documentation would evaporate. But to the extent that happens, will take several years--possibly as much as a decade. True, only a fraction of the new features affect LongJump. But improvements to the underlying infrastructure and installation process often do.

For the AgileApps wiki, we have a development version (aadev) and a production version (aawiki). 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 that becomes an additional wiki to manage. But since we don't have that, the LJ wiki needs to be updated after a release with information that was added to the AgileApps development wiki in the weeks before the release.

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 describing a new feature requires more than adding a new page. The following items need to be taken into account, as well:

• 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 (passwords can't be reset, and personal info can't be modified). 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. Otherwise, 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.

The Theoretical Single-Sourcing Solution

A single-source content solution is one possible strategy. The idea would be to use something like DITA to develop content pages that are shared between the LongJump and AgileApps wikis. The pages would be published, using conditional text or variable-insertion to change things like the path taken to access a given feature. In theory, that sort of system solves all of the problems. But there are some severe downsides:

• DITA solutions require expensive editors and/or an investment in tooling
• We would need an additional investment in tooling to generate Wiki-compatible pages, and run programs that use MediaWiki apps to insert the resulting pages into the systems.
• The shared-content pages would need to be reviewed in a development version of the wiki, in order to spot incorrect paths and other conditionally-dependent errors--which forces us into the position of having a development version of the LJ wiki, which we have been trying to avoid.

In summary, then, the "theortical" solution is likely to be impractically expensive for as long as we continue to use MediaWiki for documentation delivery. But there is one more possible alternative.

Mark Beckers is taking over writers for Terracotta and other SAG products in this area. He is planning on going the DITA route, and from what I've been told, he knows what he's doing. (For example, the three editors he's recommending are XMetal, FrameMaker, and oXygen--the only three that are good enough for production work.)

Dr. Marc Beckers – VP, Technical Communications

Marc will lead the Technical Communications team comprising of Product Documentation & Globalization. He along with his team will be responsible for user documentation for Software AG products and provide the internationalization consulting, technical infrastructure and localization project management to ensure timely and quality release of product versions in supported languages.

--from the announcement message by Thomas Albert, 20 Dec 2013

We're under a different VP, so we won't be forced in that direction any time soon. But it's remotely possible that they might have an investment in tooling that we could leverage--all depending on how they choose to approach things.