Tag Archives: DITA/XML

My high-tech adventure: Chapter 11, VR Communications, Inc.

In 1993 my wife, Anna, left IBM and started her own business, VR Communications, Inc., which has primarily worked on technical communications projects. In 1995 she converted the business to a corporation because it was hard to get consulting work as an independent contractor. The US Government had noticed that some companies were hiring people as contractors and keeping them on for a long time, making them into full-time employees, but without fringe benefits. If the companies hired another corporation, they did not have such a problem. Since 1993 VR Communications has done work for over 20 clients, including:

  • Acta
  • Avid
  • CISCO
  • Intuit
  • Kyocera
  • PayPal
  • Pearson Foundation
  • Pillar Data Systems
  • San Jose State University
  • Stanford University
  • VMWare
  • WITI (Women in Technology)

At times the business environment was such that companies did not want to hire contractors. In those times Anna took staff jobs instead of contracting. The preference for full-time versus contractor has gone back and forth many times since 1993. Some of the companies she worked for as a technical writing employee were:

  • ISI (Integrated Systems)
  • Siebel
  • Skytide
  • SLAC (Stanford Linear Accelerator Center)

The El Dorado Hills Handbook

In 2002 I left IBM, and Anna and I moved to El Dorado Hills. We had hoped to do some high-tech consulting in the area, but that didn’t pan out, so we decided to work together writing a book about El Dorado Hills that we called the El Dorado Hills Handbook. Even though there were thousands of people living there, there was no source of information about El Dorado Hills other than from the real estate developers. We made many field trips looking for information, going all the way from the Sierra to libraries in Sacramento.

The book was published in 2003 and was 312 pages long. We both did the research and photography, Anna did most of the writing, and I wrote a few of the topics myself. It was a fun project to work on, but we found that there weren’t too many people in the community who wanted to buy a book about El Dorado Hills. We even ran into resistance from people who had been in the community for a long time and claimed they had planned to write just such a book themselves, but had not gotten around to it yet. You can still find copies of the book in the El Dorado County Library.

El Dorado Hills Handbook cover

Here is Anna in the El Dorado Hills library with a copy of our book.

DITA Projects

One of our first “second-career” activities (third for Anna, who taught high school for 10 years) was documentation for an open-source technology project: a user guide for DITA, an XML-based, end-to-end architecture for authoring, producing, publishing, and delivering information as discrete, typed topics.

In March of 2006, Anna and I attended a DITA conference in Raleigh, North Carolina, because we wanted to find out more about DITA, which was then a new standard for the format of technical documentation being worked on by OASIS, a standards organization.

DITA meeting in 2006

Most of the conference speakers were from IBM, since IBM created the first version of DITA for its own internal use. At the meeting we learned that there was a need for somebody to create user documentation for the DITA Open Toolkit. The Toolkit was a reference implementation of DITA being done as a SourceForge project, mostly by IBM developers. Anna and I jumped at the chance to do this, since it would give us a chance to collaborate on a project that would use her writing skills and my software skills. We have been collaborating ever since! Together we managed to learn enough about DITA to publish the first edition of the DITA Open Toolkit User Guide in August 2006 using the DITA format.

Cover of the DITA Open Toolkit User Guide

We approached this endeavor as a way to give back to our own technical community and also to gain skills in a promising new communication technology.

Once we published the DITA OT book, we had credentials that allowed us to land many DITA contracts between 2006 and 2010. We gave DITA writing team training seminars and did technical writing using DITA. We also gave presentations on DITA to meetings of the Society for Technical Communication and the Silicon Valley DITA Interest group (SVDIG).

Us at the Silicon Valley DITA User’s Group

Here are some of the DITA clients we worked with.

CITRIX – DITA training
FedEx – DITA architecture and POC
PayPal – team training
Savi – team training
SkyTide – DITA technical writing
East Bay STC – presentation

Pearson Foundation projects

Pearson Foundation

In 2008 we spotted an interesting Internet job ad. The Pearson Foundation, a non-profit funded by Pearson Publishing (e.g., Penguin Books), was looking for a technical writer who also knew the Python programming language, to write a high school programming course for the National Academy Foundation (NAF). When we contacted them we learned that they had been looking for such a person for a long time and hadn’t found anybody. So we proposed that Anna and I do the project as a team, Anna to focus on the writing and me to focus on the Python programming. The Pearson people were very reluctant to deal with two people instead of one, but finally decided to give us a try, since they had nobody else!

NAF logo

NAF fosters partnerships between the business and education communities to provide opportunities to underserved high school students. They have helped create a number of academies of industry-specific courses. Our class, Introduction to Programming, is part of the Academy of Information Technology.

After many months of hard and challenging work we produced the first version of the class. This included lesson plans, teacher resources, and student resources written with Microsoft Word, plus over 60 Python programs. Both Pearson and NAF ended up being very pleased with our work. They even got AT&T to sponsor the programming class.

In addition to revising the Python class several times, we have since helped revise and improve NAF classes on database design and web design.

NAF Introduction to Programming

Website technology

In 2010 Anna and I began to shift our focus from technical writing to websites. We noticed after the financial meltdown of 2008 that our opportunities for writing contracts began to decline. Many times during 2010 and 2011 we were contacted by companies that claimed they were interested in a project, but after much discussion, they silently went away and nothing came of it. Some of these clients just wanted free consulting. Prior to this, Anna had been maintaining several websites, so we began to consider whether we could include website building into our technical skills so we could do more than technical writing.

In May and June of 2011 we took a class from Sam Cohen (a Drupal expert) called Mastering Drupal. Drupal is an open source web content management platform. It is like an erector set for building a web site with lots of functionality.

It seemed to us that it might be possible to publish regular DITA content on a Drupal website, which would give you lots of capability to search it and display parts of it. You could also combine structured content done by a technical writer with unstructured content written by a member of the community. This sounded like it would be fun and interesting to explore.

After we finished the class, we went on to build several model web sites to improve our skills and portfolio, and we even converted our personal site, News from Nan, to Drupal. With a little bit of Python script writing, I was able to publish structured data from our family trees to News from Nan.

Drupal version of newsfromnan.com

As of this writing (April 2012), we have created several web sites as a Drupal portfolio. They are:

  • A site about DITA containing both structured and unstructured information
  • A site about Drupal containing both structured and unstructured information
  • A sample community site for El Dorado Hills
  • www.newsfromnan.com – Our personal family site. We are experimenting with publishing GEDCOM genealogy information about our family tree
  • A nonprofit foundation site
  • www.vrcommunications.us – Our professional website
  • A law office site for out daughter Gillian and her law partner