User:Aeric/Writing and Publishing Guide

Important: This page has been updated as of Nov, 2014. Other guide pages may be out of date.

Standard Tasks

As new release dates are announced in meetings, add them to the list of Upcoming Releases
Get information on new features from developers

How to Do Stuff

Many things are accomplished using the Wiki Templates. Browse them to see what they do:

Sidebar > toolbox > Special Pages > All Pages
Namespace: template
[Go]

Of particular interest:

Template:Cheatsheet -- usage instructions for some useful templates that have similar names
Template:Variables -- a listing of variables defined in LocalSettings, and their values in the current skin

Also see User:Aeric/tests for interesting bits of wiki lore and examples of how to do things.
This file contains snippets of wiki code: MediaWiki_Notes.txt

I inherited a similar file, but it was too large to use.
So I started one of my own, accumulating tidbits as I learned them or found them in the wiki.
It started out small, and was very handy.
Over time, though, it grew too large for anyone else to use!
So you're encouraged to collect your own set of notes, unless you happen to be able to make sense out of that one.

--eric

Release Model

Dated Cloud Releases

The platform running in the cloud is updated at 2, 3, or 4 week intervals.
When an update occurs, the features previously regarded as "Coming Soon" are added to the Release Notes, with a date to indicate when the update occurred.

Versioned ISV Releases

When a new "installable version" is released, a snapshot of the dev wiki is taken.
The snapshot is given a version number.
The help link in the installable version points to that wiki so that, as features evolve in the cloud, accurate help remains available for the (now down-rev) installed platform.

For the cloud release: publishDevWiki
For the ISV release: versionAgileAppsDevWiki
On rare occasion when things have been added to dev wiki that are not included in ISV release:

versionAgileAppsProductionWiki

Note: Releases are currently staggered, with cloud releases at end of month, and ISV releases 2 or 3 times a year in the middle of the month. At those times, some new features go into into the ISV release before they are seen in the cloud.

Wikis

ljwiki -- LongJump wiki in the cloud
lj{###} -- Versioned LJ ISV wiki (ex: lj100)
aadev -- pre-release AA wiki
aawiki -- AA wiki in the cloud
aa(###} -- Versioned AA ISV wiki (ex: aa100)

Note:
A two-digit version number would probably be sufficient. The extra digit is included in case a intermediate versioned release is needed--for example: 10.1. But that circumstance may never occur. So lj10 and aa10 would be simpler--and lj101 could always be created, if needed.)

Help Links

The help link in the cloud points to the appropriate wiki:

AgileApps ==> http://agileappslive.info/wiki, which references the aa_wiki.
LongJump ==> http://lj.platformatyourservice.com/wiki, which references ljwiki.

Help links in the installable versions point to a versioned wiki:

AgileApps ==> http://agileappslive.info/aa100 (for example)
LongJump ==> http://isv.platformatyourservice.com/lj100 (for example)

(Note that the "isv" subdomain is used for the versioned wiki, to activate the "whitelabel" skin.

Ordering Tasks

These are the possible values for the doc task fields. At the moment, they map imperfectly to the manual procedures outlined below:

Target - which version of the platform is affected.
(Selects the column in the manual procedures)

AA Only - Applies to AgileAppsLive only
LJ Only - Applies to LongJump only
AA & LJ - Applies to both AgileApps and LongJump

Audience - This setting creates a partitioning into sets of things that are related to each other.
(The most important partition is at the top. Others come in the order shown.)

User-Designer - For docs read by users, sys admins, and/or application designers.

--This is really an audience designation. Separating into the 3 different kinds would be good.

API-Dev - An API change or feature that affects developers.

--Another audience designation, for the 4th kind of reader.

Code - Generally an enhancement request that contains a code sample to include.

--In terms of a full matrix, it's audience=Developer, doc type=Enhancement.

Install - An installable version feature or installation note.

--Audiencetype #5: Installer. Could be a feature, enhancement, cosmetic fix, or bug fix.

Merging the audience settings above with the activities below is tricky.

For example, the "ISV feature" activity below is just audience=Installer, activity=New Feature.
BUT, in terms of prioritizing, ISV features only become important when an ISV Release is near.
So the order in which things need to be addressed is actually a partial-ordering that is produced by a set of compound conditions:

If target=AA Only or target=AA and LJ:

activity \ audience:	User	Designer	Sys Admin	Developer	Installer
Bug Fix	10	12	14	16	18
Cosmetic Fix	20	24	30	34	62
New Feature	22	26	32	36	64
Enhancement					68
Release	50				70
Doc Enhancement	90	92	94	96

If target=LJ Only:

activity \ audience:	User	Designer	Sys Admin	Developer	Installer
Bug Fix	10	12	14	16	18
Cosmetic Fix					62
New Feature	22	26	32	36	64
Doc Enhancement					68
Release	50				70
Cosmetic Fix	80	82	84	86
Enhancement	90	92	94	96

Notes:

Rules should be applied on record update only when ISCHANGED is true for one of the independent fields in the ordering equation (activity, audience, or target), using the expression:

OR(ISCHANGED(activity_766224774), OR(ISCHANGED(target_766224774), ISCHANGED(doc_type_766224774)))

where doc_type_766224774 is the audience field

They should also execute only when all three fields are non-empty, using the expression:

NOT(OR(ISNULL(target_766224774), OR(ISNULL(activity_766224774), ISNULL(doc_type_766224774))))

The ordering values create priority-partitions. Within each partition, the order is AA, then AA/LJ, and then LJ--primarily to keep similar kinds of tasks together.

The tricky bit is that the priority matrix changes as a release draws near. So, for a complete ordering that reflects current circumstances, there should be multiple priority matrixes, with the ability to choose the one that is currently in effect. (But the need for that feature evaporates if the task list can be kept short.)

Manual Procedures

These procedures are manual. The procedure to use depends on the type of activity and the target of that activity (i.e., the product it applies to).

Bug Fix

(P1=feature not usable)

AgileApps	LongJump
Fix AA dev wiki (`aadev`) Fix AA cloud wiki (`aawiki`) Fix current ISV wiki (`aa###`)	Fix LJ cloud wiki (`ljwiki`) Fix current LJ ISV wiki (`lj###`)

Cosmetic Fix

(typos, wording, better text)

AgileApps	LongJump
Modify the AA Dev wiki. (Changes will migrate at next dated release.)	Skip small "cosmetic" improvements.

Enhancement

(New page, vastly improved page, PDF article update.)

AgileApps	LongJump
Modify the AA Dev wiki. (Changes will migrate at next dated release.) For a big new page or update to a PDF, add an entry to the "New in the Docs" list in the dev wiki Release Notes.	When an equivalent AA page is reorganized: Reflect the reorg in the LJ wiki to ensure that future changes can be made without difficulty. Skip all other AA improvements as "cosmetic".

New Platform Feature

AgileApps LongJump

Add to Dev wiki: http://agileappslive.info/aadev

For release notes:

If ISV release is pending, add entry to New Platform Features section of ISV release notes.
Otherwise, add entry to New Features section at top of standard Release Notes.
If the Release Notes page is a redirect to Version NN.m Platform, convert the page:
- {[subst: ISV Release Notes}}
- Change the link that goes to the earlier-version release notes at the top of the page
Generally, add a Learn More link. Otherwise, embed a link in the blurb. (In rare cases, there is nothing to link to.)
Review the entry with SMEs

For a new page:

Add the appropriate category to the page:

<syntaxhighlight lang="xml" enclose="div"> -- to be created

</syntaxhighlight>

And add an entry to the appropriate index page:

If feature is in AA wiki, get release notes blurb and docs reviewed there, first.
Add docs to the LJ cloud wiki:
http://lj.platformatyourservice.com/ljwiki
Add entry to "New Features" section at top of Release Notes:
http://lj.platformatyourservice.com/ljwiki/Release_Notes
Include link to the doc page

Note: There is no "pre-release" wiki. Installations point to a versioned wiki, so they're good. Cloud users may see a future item, but for only a few weeks at most. (Fewer LJ users are scanning the Wiki than the AA wiki. SE's in the field are scouring that one.)

Cloud Release

(A dated release)

AgileApps LongJump

Final cleanup / release prep:

Monday: Circulate release notes to developers and Q/A. See if there are any additions.
Wednesday: Copy release notes to aawiki. Send link to Janhavi.
Find and fix all references to Template:TBD
(As an alternative, leave them in place and remove them from the published wiki.)
Verify that any references to Template:Beta are still appropriate.
Remove the release date from the table of Upcoming Releases
Release notes

First release:
Convert Release Notes page from redirect to date header.
If a dated ISV release preceded this one, comment out the date header for that ISV release.
(So cloud users see a single set of features for the latest date.)
Change "New Features" at top of Release Notes to the date of the release.
Create a another New Features section for any items that didn't make it in time.

Push the messages file

Launch VPN
svn update
Invoke script c:/www/scripts/upload_messages.bat
Review the results. Press any key to close the window

publishDevWiki (script)

After Publishing
- In the archive dir, download the production backup made during the process.
- Delete one or more of the old ones. (Only 2 or 3 need to be kept. They consume space in the daily "disk-image" backup made by the system.)
- If an ISV-release date header was commented out in the Release Notes, uncomment it.
  
  Future cloud users will see two sections where there was one before. No matter.
  
  Next ISV release will have the dated section at the bottom of that release, and the top of the previous release. No matter.
- Post announcement to the AgileApps Yammer Group
  Template: #Cloud Release Blurb

Release notes

First release: Convert Release Notes page from redirect to date header.
If a dated ISV release preceded this one, comment out the date header for that ISV release.
(So cloud users see a single set of features for the latest date.)
Change "New Features" at top of Release Notes to the date of the release.
Create a another New Features section for any items that didn't make it in time.

There is nothing else to do for a LJ release. (By choice, the wiki always reflects the latest new features, even if they're not out yet.)

After Publishing

If an ISV-release date header was commented out in the Release Notes, uncomment it.

Future cloud users will see two sections where there was one before. No matter.

Next ISV release will have the dated section at the bottom of that release, and the top of the previous release. No matter.

New ISV Feature

(installable version feature or installation note)

AgileApps LongJump

First change:

Remove redirect in ISV Release Notes page
{{subst: ISV Release Notes}}
or copy most recent version

Document the feature
Add link to ISV Release Notes

First change:

Remove redirect in ISV Release Notes page
{[subst: ISV Release Notes}}
or copy most recent version
{[subst: ISV Release Notes}}
or copy most recent version

Document the feature
Add link to ISV Release Notes

ISV Release

(version-numbered)

Release Prep

Circulate release notes to developers and Q/A. See if there are any additions.

Send out help links with final slash to the release admin:

(Context-sensitive help concatenates a page name to the help URL, so final slash is needed.)

Add version number to header logo and favicon
Path: www/custom_logos
aa100.ico ==> aa###.ico

Use eyedropper to select teal
Trebuchet MS, normal, 10

aa100.png ==> aa###.png
(watch directory -- defaults to last, not current)

Edit using SnagIt editor
Logo Text: Gil Sans MT font, bold, 48 pt. Teal color
Version#: (TrueType) TT Arial, 12pt, greenish-gold color

Font is not TT Arial Unicode MS. It's further down.

Color is in the middle of second row of colors, right most of two adjacent w/similar color.

lj100.ico ==> lj###.ico

Use eyedropper to select blue
Text: Trebuchet MS, normal, 12

lj100.png ==> lj###.png

Version#: Gil Sans MT, 36 pt, custom blue (sample existing if not in palette)

Add images to SVN and commit changes
Push images to server

Release

AgileApps LongJump

Final cleanup:

Find and fix all references to Template:TBD
Verify that any references to Template:Beta are still appropriate.

In AA Dev wiki:

Remove the release date from the table of Upcoming Releases
Move "Release Notes" page to "Version ##.# Platform", leaving a redirect
Change the link that goes to the earlier-version release notes at the top of the page
Move ISV Release Notes to Version ##.# Installable, leaving a redirect
Regenerate and re-post Javadocs to dev wiki
(Does not apply to LJ, due to AA-specific APIs. E.g accessProfile.)
Run the versionAgileAppsDevWiki script

If needed, run the older x_versionAgileAppsProductionWiki to version the production wiki.

The process is needed if the dev wiki happens to have things in that are not in the ISV release.

But the reverse is more common: Things have been added to the development platform
that will be in the ISV release, but which are not yet available in the cloud.

After the versioning script completes:

Copy items from New Platform Features in the ISV release notes to the
New Features section at top of the (cloud) release notes page.

Post announcement to the AgileApps Yammer Group.
Template: #ISV Release Blurb

Modify Readme for SAG Empower page:

SVN:/techpubs/release_blurbs/AgileAppsReadme.html

Adjust ##.# in heading
Adjust 5 links to aa###
When the new platform release is available, send to the current release maven
(Sherwin, Sergey, or Sherwin) to include in the release notice sent to Steve O'Brien

Review existing pages at http://empower.softwareag.com
(Use the instructions in the accompanying README to go to the product listings.)

Send global documentation link:

Adjust the code below
Send to Sabine Winterbauer for inclusion in http://documentation.softwareag.com
Backup: Send to Dr. Marc Beckers--but only if the previous process fails

Post-release follow-up

Verify the Empower entry.
NOTE: The Readme link goes to a download page. Clicking the "Download" link in that page then displays the Readme. That's the best that can be done with the Empower site software. There is no way to directly display the Readme when clicked. (The best that can be done is to prevent the user from having to download the README to read it.)

Once the Empower entry is published and verified by self and Uday, use the ISV-release blurb template below to post a note to the Yammer group.

Copy new features and bug fixes from installable release notes to the release notes for the next cloud release.

Move "Release Notes" page to "Version ## Platform", leaving a redirect
Change the link that goes to the earlier-version release notes at the top of the page
Move "ISV Release Notes" page to "Version ## Installable",
leaving a redirect
Run the versionLongJumpWiki script

Sample Announcements

Sample Release Blurbs for Yammer Group

Note: When I put in a link to current release notes, as here:
http://agileappslive.info/wiki/Release_Notes, then the paragraph Yammer would have found on 17 Jan is displayed. It's not showing the paragraph at the top of the most recent version of the page.

The workaround is to leave "Release_Notes" off of the URL. That causes the first paragraph from the main page to appear. "Release_Notes" can then be added back, leaving at least a semi-meaningful blurb on the page.

Cloud Release Blurb

Date the blurb for the day after the wiki is published.
(The wiki is published the day of the actual release, but the actual release may not happen until late in the evening--so we always tell customers that the release will be available the next day. The blurb should do the same.)
Post the blurb to the Yammer AgileApps Group

A new version of AgileApps Live will be in the cloud on Sat, xx YYY 2014.

Highlights include preference settings to determine how records are displayed, email signatures, editable subforms, external lookups, external data sources, and fault handling for web services, plus documentation enhancements.

Learn more: http://agileappslive.info/wiki/Release_Notes

ISV Release Blurb

Post the blurb to the Yammer AgileApps Group

Version ##.# of the AgileApps Live installable is available at empower.softwareag.com

Highlights include ...

Learn more: http://agileappslive.info/***ISV_WIKI***/ISV_Release_Notes

Note: Don't include the https:// to make a link that goes to the Empower site. Once you do, there does not seem to be any way to get Yammer to recognize the Release Notes link. (It looks like it will handle only one link at a time, and the https:// always dominates, whether it is added first, second, or together with the other.)

HTML code for documentation.softwareag.com

Under source control at techpubs/release_blurbs:

        AgileApps Live:

       <a href="http://agileappslive.info/wiki">
           AgileApps Live in the Cloud
       </a>

       <a href="http://agileappslive.info/aa101/ISV_Release_Notes">
           AgileApps Live Installable Version 10.1, for on-premise installations
       </a>

</syntaxhighlight>

Scripted Procedures

These procedures are accomplished by logging in to the Wiki platform and running a script.

Publishing the AA Dev Wiki

First, prepare the development wiki for publication. Then execute the publishing process.

Preparation:

Find and fix all transclusions of Template:TBD
In the dev wiki, change the Coming Soon heading to reflect the release date.
http://agileappslive.com/aadev/Platform_Features
Leave unimplemented entries under Coming Soon or, if there are none, comment out that section

Publication:

Using PuTTY, log in to the Rackspace server
Run scripts/publishDevWiki to copy the contents of the
development wiki (aadev) to the production wiki aawiki
This process makes a backup of the production wiki.

If there is ever any need to revert to a previous version,
run scripts/restoreWikiInstructions for a list of steps

Wiki Backups

A MediaWiki site contains a number of wiki files and a database.
The PHP files and wiki content files are in the {wikiName}/ directory.
Each Wiki has its own database.
The database contains page contents and edit history. Data is exported to a .sql file using mysqldump, and imported using mysql.
This script makes a dated zip file that contains the .sql file and the aadev directory folder:

./scripts/backupDevWiki

The archive of database backups maintained on the server is at /usr/share/mediawiki/archive.

To back up the development wiki:

Using PuTTY, log in to the Rackspace server
Run scripts/backupDevWiki to create the backup file (dev_backup_<date>.zip) in the archive/ directory.
Use FileZilla to download the backup to the local system

Note: A backup of the production (cloud) wiki is made automatically when the Dev wiki is published.

Wiki Versioning

When a major new release of the platform's Installable Version occurs, a point-in-time snapshot of the current wiki needs to be captured, for continued reference by an on-premise installation that won't have features that were added later, to the platform running in the cloud.

To make that work, the help link in the cloud instance points to .../wiki, while the help link in the installable points to .../{version}. Eg. .../aa90

To make that version:

Using PuTTY, log in to the Rackspace server
Run scripts/versionProductionWiki to create the new Wiki version
Follow the instructions at the end of the script to add a version number to the wiki header image and favicon.

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

User:Aeric/Writing and Publishing Guide

Contents

Standard Tasks

How to Do Stuff

Release Model

Ordering Tasks

Manual Procedures

Bug Fix

Cosmetic Fix

Enhancement

New Platform Feature

Cloud Release

New ISV Feature

ISV Release

Release Prep

Release

Sample Announcements

Sample Release Blurbs for Yammer Group

Cloud Release Blurb

ISV Release Blurb

HTML code for documentation.softwareag.com

Scripted Procedures

Publishing the AA Dev Wiki

Wiki Backups

Wiki Versioning