Case study: Version Controlled Documentation - Migration

In this article we will describe  migration of the original ObjectGears system documentation to the new Version Controlled Documentation. The original documentation was stored in files (each article was repreented by a particular file) and it did not meet the needs anymore.
Therefore, we have developed a new documentation that has several advantages:

• search functionalities
• it is based on ObjectGears system and therefore it can be further enhanced and extended
• role based access
• enables more versions of a single article
• logs access and invalid references
• support for tags, language localization, archiving of old articles
• support for editors with identification of articles requiring attention
• support for database back up

 

We have phased the migration into several steps.

1. preparation - back up of the old documentation  and installation of the new ObjectGears instance with model Version Controlled Documentation
2. import - import of files with data into the database
3. data cleansing
4. final release of the documentation to the production server and publishing

1. Preparation
The first step was creating back up of the old database in order we can go back and eventually find out original articles. This is a best practise in case of any migration because things do not always run as you plan.

We have checked the files with articles and deleted those without any content. This resulted in files that should be migrated.
We had to move also pictures that were originally in the root folder of the web application. We wanted to move them to the ObjectGears web instance subfolder ImagesData in order we could work with them further in ObjectGears. At the same time we have created a new folder Images_1710, where we we copied all the pictures from the version 1.7.1.0. We have redirected (in step 3) all the links to pictures from all the articles, that originally refered to pictures in the folder Images, to this folder. Since the new documentation runs in ObjectGears, it is no good to refer directly to the folder Images, because a new ObjectGears version can bring new pictures in thís folder and this would impact articles about previous ObjectGears versions. For new versions we will create a new subfolder in order we ensure links to correct pictures in the new version.

 

2. Import
We have utilized a function from the Admin tool for the import, which enables to import files (pictures or texts) into a class. In our case we have imported text files.

We did not import files directly to the target tables but to auxiliary classes. These classes contained columns for the imported data and another set of columns for information about language, version, topic or parent article. After import we have updated these extra columns step by step by means of SQL scripts that we prepared including links between articles.

A single imported file then represents one or two records in the target classes. One in the article and another one in the article_text. Files for other languages then insert a record  to the article_text only. This was another reason for using the temporary auxiliary classes. We have set a language and version 1.7.1.0 to all the articles.

After checking the data in auxiliary classes we have created a script that pasted the articles into the target classes for article and article_text. We have inserted the imported text into two fiedls: New text and Published text. At the end we have imported class hierarchy - relation of the article to the parent article.

We did not import links "See also", that connect articles each with another by means of links at the end of the text. Reason for that was few records for import and therefore we have updated these data manually via GUI. It was much easier and faster then to prepare also these data for migration. Another advantage was that this job could have been performed by users, not necessarily developers and therefore, it could ran in parallel.

While the developers were preparing and tuning migration scripts, other colleagues were checking files to be imported and results of test imports. After this the original files were no more needed.

3. Data cleansing
After import we proceeded to data cleansing. We defined a topic for the main articles. Child articles were checked to have a correct parent article.

There were appr. 30 articles that were created but not included in the hierarchy. This was not obvious in the original documentation. In the new documentation such articles can be immediately filtered. Newly such articles cannot even be created.

The change of the documentation system brought also a need to change URL in links betweeb articles. This change was performed in the database - by replacing the original address Help.aspx?h= for a new one ./-vcd/_language_/. After that we have tested all the links just by clicking on them and identified cca 50 erroneous links that we corrected.

We found several pages that were not translated. Information about need to translate was lost apparently. Now, we simply checked them to Translate and this job will be done by editors.
This is an example of advantages of the new system. You just check an action to be performed and do not need to write to anybody. Articles marked with indications or identified based on a certain logic are automatically displayed in the overviews for editors.

We have also removed article headline from the text. It is now stored in a separate column of the classs article_text and it is inserted automatically into the page.

4. Final release
After checking the articles and final tuning the model with Version Controlled Documentation the database was moved to the production server with the last version (at that time not yet released in public).

As a last step we have added redirection from the old URL Help.aspx?h=... to the new one  vcd/... , in order original links and links from Google work well. We set a permanent redirect to avoid penalization by Google.

Example of the script for redirection:

if ( OGErrorInfo.IsInvalidPage && OGErrorInfo.Request.Url.AbsolutePath.ToLower().Contains('help.aspx'))
{
  OGErrorInfo.RedirectPermanent = true;
  OGErrorInfo.RedirectToUrl = './vcd/en-us/' + OGErrorInfo.Request.QueryString['h'] + '/v/1.7.1.0/';
}