By Bindu Nayar

A Reality Check

So at what stage in the Software Development Life Cycle (SDLC) does documentation get done? If you said “right at the start”, then your organization is unique. The fact is that no matter how much we propound the benefits documentation presents to our customers and the organization, in reality, it is probably the last thing on the minds of the engineering team – probably rightly so, as in most cases, without code, there can be no documentation. But most of the time, reviews are done only towards the end of the release. This is of course not by choice, but due to the fact that documentation in most cases gets generated only after the coding is done.

Dealing With Change

Yes, you have all the bells and whistles—   the effort estimates, the plan and the schedule.  You have even convinced the engineering manager to spare the developer’s time for the review cycles. But what typically happens is that between the time you write and the document gets reviewed, what you have already written seems a bit different from the actual behavior of the software. While most of the time the changes can be subtle, in some cases it can be drastically different.

This may lead to a lot of situations where last-minute rushed reviews are done and corrective measures are taken to ensure that the documentation aligns with the workings of the software. When it comes to such fire-fighting situations, many a time crucial and critical details are missed out and this may lead to lot of complications and inconveniences for the customer.

Have you wondered how good it would be if there exists a system that publishes your documents as you write and you can get the reviews done in an online manner?

A system that will help you provide a preview of your documentation to your reviewers, thus aiding in a more collaborative and effective review system.

Analysing the Need

Do you really have a need to implement a system like this? Ask yourself these questions to ascertain if you really need to implement a Publish-As-You-Write system.

1. Does the product/project you are working on have a long development cycle and is expected to go through a lot of churn before it is released to the customer?
2. Do you have frequent code drops that include documentation as a deliverable?
3. Do you have multiple reviewers whose approvals are required for the documentation to be certified as done?
4. Have there been instances when the final content that got shipped with the release greatly differed from what you had initially written?

If you have answered “Yes” to most of the questions above, then a system like this will help you iron out the operational issues associated with getting reviews done on time and in an effective manner.

Principles of the Publish-As-You-Write Model

The concept of publish-as-you-write is in reality, a simple process that works on the principle of What, Where and When.

The 3 W’s

1. What:  Identifying “What” has changed
2. Where : Determining the location “Where” the changes should be published.
3. When : Timing the frequency to determine “When” the changes should be picked up.

Let’s see how you can implement a system like this without much effort and cost.

The Inner Workings of a Publish-As-You-Write Model

1.   Central Repository of Source Files

Having your source files version controlled is a must-have in today’s world considering the rapid pace of development and the need to work on parallel releases/projects at the same time. But if you do not have a version control system in place, do not worry.

To implement a publish-as-you-write model, all you need is a central repository of files.  The format of the files also doesn’t matter—be it Word, Frame or Epic Editor.

2.   Identifying and Processing What Has Changed

This part of the process involves two steps:

1. Watch
2. Pick

Watch

This step is to have a machine that will double up as a build server. This server will run scripts that will “watch” the central repository to locate files that have undergone any change. You can have a Windows/Mac/Linux machines to act as a build server.

Pick

To “pick” up files that have changed, you will need to write scripts that can identify the change in timestamp details.You can pick up any scripting language like Perl, Ruby, Phython, or Java.

3.   Packaging the Content

If the files you have submitted to the repository is in a format like XML, you will need further processing to make it in consumable. For instance you will need to use content transformation methods like XSLT, XSLFO to get content into popular formats like HTML and PDF.

If you are using a Word processing software like MS Word and are planning to give your customers documents that are in PDF format, all that you need are drivers that will generate the PDF for you. In such a situation, apart from the free/licensed drivers you will not require any further content regeneration tools or systems.

At this stage of the process, your files are in a format like HTML or PDF and this is what kick-starts the process of publish-as-you-write.

4.   Publishing the Documents

The files that have changed now need to be pushed to a location where they can be viewed for the review purposes. For this you will need a web server that can host the content.

If your company  has an open publishing policy, all that you need to do is set up the web server framework to list all your documents for review.

If your production environment demands that you share your documents with your clients (outside your company network) for review, you can set access control. Just share the login credentials with them and they can access and review your guides.

5.   Timing the Builds

How often do you want the builds to happen?  You can make it as frequent as every two hours or have it generate a build at the end of the day. To make the process automatic, include the frequency parameter in your scripts to do the fetching and generating at predetermined intervals.

Conclusion:

The Publish-As-You-Write system is a simple and effective means to avoid fire-fighting situations that typically happens in most of the documentation development scenarios.

As the document creation and review are cyclical, it helps in better operational alignment with the project cycles. This in turn reduces the load on your SME’s or stakeholders to do last-minute reviews and corrections. So with your reviews done and the documentation live for everybody to see, you have managed to check a documentation deliverable off the list of to-do’s. When its time for the release all that is required is package it or publish it to a live site.

The interesting and appealing part of the autobuild system is that you do not need great technical expertise to set up a system like this. Your Production Specialist can help you get a system like this in place. But, if you do not have the luxury of an in-house Production specialist, engage with your development engineer to get the scripting done. After the scripts are done, its all about just scheduling the scripts and sitting back and watching what you write, come online in a matter of hours.

Bindu Nayar is a Lead Technical Writer with over 11 years experience in the technical writing field with core experience in protocol and developer documentation. In addition to primary role of authoring, she is currently involved in project management activities at Novell.