Information Mashup Approach for Product Documentation – Concept

If you want to increase your own personal and also your group’s (or company’s) productivity, first follow Don’t-Repeat-Yourself (DRY) principles wherever possible. One such area for  cutting out repetitions is product documentation. Now-a-days companies have even started out-sourcing the technical documentation part. This post is not for analyzing whether it is good or bad from a Time & Cost perspective of a project but not having a technical documentation frameworkcan have the following effects:

1. Increase the communication overhead between the development team & the technical writer(s).
2. Increase the possibility of repetitions from the tech-writer which is already documented some-where by the development team – even in source code.

In this post, I am proposing an approach to product documentation (could be product user guides, architecture documentation, etc.) or even project review presentations which leverages the artifacts produced by the software development & testing teams as much as possible so that repetitions are eliminated to a large extent.  Of course, it requires some discipline from the team and also some level of ALM tools integration & automation. Last but not the least, leveraging artifacts produced by development & test teams helps in keeping the documentation in-sync with the code – one of the major cribs we hear from software maintenance teams !!!

Solution Control Flow Diagram

The diagram below shows what are the different tools required for information integration. Product documentation or project presentation is done in a Collaboration/Wiki Editing tool (such as Atlassian Confluence or wiki built into Trac or ThoughtWorks Mingle) to enable a few people to collaborate: Technical writers to edit and post content and team members to review it.

Arch. of Information Mashup for Product Documentation

The information in the end-user or internal developer documentation is mashed up from three sources, which are:

1. New features for each product release is captured in the Task/Defect Tracking (or Project Management) Tool (PM/DT Tool) such as open source Trac, Atlassian JIRA or ThoughtWorks Mingle.
2. New screen captures, screen flows and test cases/scripts for each of the new feature is stored in the Requirements/Quality/Test Management Tool (TM Tool) such as ThoughtWorks Twist, free XStudio or open source Salome-TMF.
3. The Software Configuration Management (SCM or VCS Tool) has versioned XML configuration & source code files. The information that can be extracted from embedded comments in source code are:
   1. Configuration parameters in XML configuration files with their embedded comments.
   2. Embedded comments in source files which can be extracted using tools such as Javadoc – for API documentation.
   3. Class Diagram, Sequence Diagram and Layered architecture diagrams.

All these three different sources of information are integrated in the set of Wiki page templates. By having templates for offline documentation output targeted for different readers, we promote consistency and re-use across the organization. The macros and tech. writer entered content in the set of wiki pages are converted to the final format – either ppt, pdf or html pages – by the publishing pipeline engine. This uses a set of custom stylesheets for adding custom header, footer, document front page, etc. and also output format specific conversion. Finally, once can even automate the generation of product documents by incorporating the offline document generation in the build script used by the CI server.

The enabling features used in this solution are:

1. Published (if not open) interface (either a REST or web service) provided by the tools used in the solution. Most tools currently available – both commercial & open source – provide a published remote interface.
2. Macro mechanism supported by most of the wiki tools, for dynamic wiki content customization.
3. Custom macros required to extract the necessary information from the tools. In cases where this is not readily available as plug-ins, new plug-in macros have to be written.

Usage Scenario for End-User Guide Documentation

A product’s end-user guide documentation typically contains: Different end-user roles (if any), the needs / goals of each of the end-user roles that the tool fulfill, terms & definitions used in the product & its interfaces, the different UI screens for each end-user role & the information contained in those screens, a few UI screen flows for achieving specific end-user goals and descriptions of any product configuration parameters which are not available thru’ the UI.

To incrementally generate an update for the document, the end-to-end Traceability Information (TI) from feature to code to test cases are required and they are of two types:

1. Feature (or ticket) to source code in Defect/Project Tracking Tool – called “Type 1 TI”
2. Test case(s) to requirements/feature/story in the Test Management Tool – called “Type 2 TI”

Assuming that we have User Guide for the current version of the product, R(i), creating a new version for the document broadly requires carrying out the following steps manually:

1. Generate the list of new features added to the product – can be retrieved from PM/DT Tool using query: “All new features committed in release R(i+1) and their short description”.
2. For each new feature, F(j), get the list of test cases and the scenario captured in automated testing tool for each test case – may be retrieved from TM Tool using “Type 2 TI” and query which looks like: “Get all Test Cases  (TCs) created for the new feature F(j)”.
3. For each TC(k), get the screen flow from the test case scenario of the captured screen shots.
   1. – If it is modification of existing screen, retrieve the changes in the screen template file (from SCM) by using “Type 1 TI” and identify the changes from the version tagged with the previous release Ri.
   2. – If it is a new screen, retrieve the screen description from the embedded comments in the screen template and the description of the screen fields.
   3. – Add any new configuration parameters that are added if any, with the description extracted from embedded comments.
   4. – Create a screen-cast from the screen-shots captured in the UI automation tool and also the annotion information from the last two steps.
4. Repeat the above steps 1 to 4,  for features which are modified (mostly enhanced) from the previous release R(i). For enhancements, existing sections in the document have to be amended or modified.
5. Generate the list of features removed from the previous release. The documentation related to these features have to be removed from the existing documentation.

Future posts related to this will have more implementation details & how some of the necessary information can be captured in the three repositories.

Posted in: Documentation