Table of Contents

Virtual Helping Hands

Zuora

KnowNow

CoSine Communications

Electron Economy

BrightInfo/Annuncio Software

Progress Software

Quality is Important

I've managed projects and have done technical writing, editing, and indexing for many major companies, often on long-term and renewed/return contracts. My contracts get renewed because companies like what I do and how I do it.

I manage all projects with care, attention to detail, and a not-quite-obsessive concern for high quality and customer happiness.

I also have a genuine liking for and appreciation of a wide range of human expression, so I get along well with a lot of people, even many who are considered by others to be difficult or even impossible to get along with.

I use a combination of standard project management practices and my own custom tracking and reporting documents.

For my actual documentation work, I use a wide variety of industry-standard tools.

 

The following paragraphs provide in-depth information about the major contracts I have held since 1998 as a Technical Publications Consultant. For a summary of all contracts held, including those prior to 1998, see a brief contract history.

Most of my experience has been with documenting software, and I have many years of experience documenting highly technical products and concepts for software and Web developers and system administrators. However, I also have many years of experience documenting products for a range of users, including creating accessible, useful, and friendly documentation for non-technical users.

Senior Technical Writer, 07/2009 to present, Virtual Helping Hands

Virtual Helping Hands is a coalition of four groups working to make Second Life™ universally accessible (i.e., accessible to anybody, regardless of disability, ethnicity, or social status).

Responsibilities

On a volunteer basis, I have signed on to create the documentation for the Max Assistive Technology project, a suit of tools that provide a virtual guide dog inworld. ("Inworld" isn't a typo—it is the term used for activity inside the Second Life virtual world.) These tools initially are providing accessibility to those who are blind or visually impaired, though other types of disabilities are also accommodated by this technology.

My years of paying attention to the latest accessibility guidelines, W3C and otherwise, and implementing them on my own Web site as well as in all documentation I work on, have contributed to making this documentation accessible. It is being tested by blind and visually impaired users with screen readers, and will be converted to inworld text as well.

Tools

I am using MadCap Software's Flare to create the Max Assistive Technology documentation (currently in first draft stage). The geographically distributed team uses Skype and email for most communications.

Senior Technical Writer, 07/2008 to 03/2009 and 9/2009 to 10/2009, Zuora

Zuora is an e-billing solutions company. For their customers, they provide an API for the purpose of integrating Zuora's billing system with the customer's Web site. In addition, they have a Wiki that provides user documentation for their Z-Billing and Z-Payments applications.

Responsibilities

Starting from scratch, in the earlier period, I wrote an API Developer's Guide for that API, creating and maintaining the documentation in online help format for delivery on Zuora's Developer Network. To obtain the needed information, I used a number of different resources: the API's WSDL; an in-house, online development resource; other research; and developer interviews.

I also created documentation plans, release notes, and Web (HTML) and Wiki pages for the Zuora Sandbox and, later, the Developer Network, as well as creating and maintaining internal Wiki pages for technical publications.

For all documentation, users included software programmers and Web developers.

In the later period, I edited their user documentation, which is in Wiki format, writing new material and bringing each page into a consistent standard according to the in-house style guide. I also edited the underlying code using the MediaWiki formatting codes.

Comments

As with other contracts, I feel very privileged to have worked with the Zuora team, which includes an international team.

Tools

I used MadCap Software's Flare to create the API documentation and Adobe's Dreamweaver CS3 for all Web pages. This was the first time I had used Flare. I am very pleased with it as compared to other help authoring tools I have used in the past (WebWorks, RoboHelp).

Other tools used included Photoshop CS3, SnagIt, Microsoft Office (all products), SVN (source control; I used a Tortoise client) and Bugzilla (a bug database). The geographically distributed team uses Skype and email for most communications.

Senior Technical Writer, 09/2002 to 04/2008, KnowNow, Inc.

As a start-up, KnowNow offered many advantages, including a large number of responsibilities and a wide range of projects and tasks. KnowNow closed its doors at the end of April, 2008.

KnowNow had an enterprise-level, real-time, publish-and-subscribe (Web) server (called LiveServer) and components using a very close relative of mod pubsub.

Some applications used smart client methodology built on top of the WinInet and Winsock API (using FTP and HTTP protocols to access the Internet for exchange of data).

As the suite of products evolved, SOAP was added, some RESTish architecture was being worked on, and RSS clients that could use Live Server were added. One of the larger suite of products added was an enterprise-level set of tools for system admins called Enterprise Syndication Solution (ESS).

Responsibilities

I managed all documentation for all products. I planned, researched, wrote, edited, indexed, and delivered all manuals, taking screen shots and performing other usual writing tasks as needed; used the bug database to keep on top of problems and changes; installed and used the software, learning it in depth; wrote release notes; coordinated and ran documentation reviews; and gave input to the GUI design. I also rewrote software error messages for clarity and rewrote or wrote GUI tooltip messages. In addition, I contributed to KnowNow's internal Wiki, which was primarily used to track projects..

Documentation types primarily comprised system administration manuals, developer’s guides, end-user guides (for Web-based applications), release notes, read-me files, and API documentation delivered in PDF; online, context-sensitive help; and XHTML formats. Depending on the documentation, users were system administrators, software programmers, Web developers, and end users of consumer products.

Product components were written in a number of different languages (primarily Java, JavaScript, Tcl, and C++). When I took on the responsibility for the release notes, I converted them from plain text to XHTML with CSS, then maintained them in that format. I worked with a cross-country and global development team. (Compliments.)

Comments

I had the great honor of working with smart people who cared about the quality of the product and who knew that, for software especially, the documentation is a part of the product. (And who also appreciated the fact that, for the first time, they had a technical writer who actually installed and used the product.)

The team included people working remotely, including an excellent team in India.

Shortly after I began work there, I became and remained KnowNow’s sole technical writer until the day KnowNow closed its doors. As time passed, the product line grew and so did my responsibilities and the number of manuals. When I started, there were two products with three manuals of approximately 200 pages total. By the end of my time there, there were nine products and eleven manuals with over 1,800 pages total.

Tools

FrameMaker 7, Dreamweaver CS3, Acrobat Professional, Photoshop CS3, SnagIt, Index Tools Professional, Microsoft Office (all products), WebWorks Professional 7, Perforce (source control), Test Director (bug database), Bugzilla (bug database).

Indexer and WebWorks Template Developer, 2001 and 2002, CoSine Communications

CoSine Communications made network hardware and software. CoSine is no longer in business.

Responsibilities

Indexed two manuals, one for command-line-interface (CLI) routing software and the other for routing software with a graphical user interface (GUI).

Also, created a custom WebWorks template to work with the CoSine FrameMaker templates. (Compliments.)

Some of the concepts I needed to understand in order to index these manuals: ATM, crypto maps, digital certificates, DS0, DS1, and so on (and European equivalents), filters, firewalls, frame relay, FRoIP, IKE, IPSec, ISAKMP, OC-3c, packets, proxies, SONET, tunnels, VCs and VCIs, VRs and VIs, VPNs, and much, much more. (Much of my knowledge was gained previously while working for a telecommunications company, Next Level Communications.)

In addition, I needed to understand the software itself well enough to index its documentation, and to make suggestions and some light corrections to the manuals as I indexed them (with permission, of course).

I also created some unique spreadsheets and modified my ongoing set of spreadsheet tools.

Comments

These projects went fairly smoothly. The indexing had to be done a few chapters at a time as the writers were under deadlines and were continuing to work on the books as I was indexing them. This introduces some challenges in indexing which I resolved in various creative ways.

The WebWorks template development went smoothly until the template was tested in "real life" situations. Then we encountered problems with compatibility of the selected template (the WebWorks Help 2 style) and a few of the in-house system configurations. We finally resolved this by having me create a dynamic HTML template. After I resolved these issues, the company was able to convert books into online help that they had never been able to successfully convert using their previous WebWorks template.

Also, everyone at CoSine is a pleasure to work with.

Tools

FrameMaker 6, IXGen, Index Tools Professional, Excel, WebWorks Professional 6.

Senior Technical Writer, 12/2000 to 06/2001, Electron Economy

Electron Economy was later purchased by Viewlocity.

Responsibilities

Documented business solutions software for a supply chain event management (SCEM) eCommerce platform supporting many different formats: EDI (X.12, EDIFACT, TRADACOM, ODETTE), XML, RosettaNet, HTML, SAP IDOC, JDE Z-Transaction, and many others, that could be used by different companies to communicate among themselves.

Created a document plan and associated spreadsheets for an overview document that was to describe every aspect of the platform (a constantly moving target). Wrote user’s manuals, system integration guides, administrator’s guides, and API guides.

Created document plans for additional manuals that I was to write, which were for software components in the platform. Wrote one of those manuals for the Process Intelligence Manager, a product that performed business and supply chain forecasting and business analysis tasks. It had a built-in set of business rules that could be used, as well as customizable rules, such as “If supplier A is selected, add three more weeks to the lead time.” The custom rules could be made as simple or complex as desired. The rule building blocks included support for if statements and case/switch statements, variables, constants, and configurable drop-down parameter lists. My training in statistics, along with my understanding of financial formulas and terminology and computer software, were very useful in writing this manual.

When I produced my first draft of the manual for review, one of the chief software developers on the product exclaimed that he was surprised and amazed at how I had written so much, so accurately, based on a single interview with him. This case is an example of how well I am able to document a product by performing independent research and by extensively using the software itself.

Out of my experiences with the software, as well as previous courses and informal training on usability testing and product design, I made several suggestions for improving the GUI, all of which were implemented.

In addition to completing my own tasks, I developmentally edited several manuals written by other writers and, drawing on my educational training and background, on my own initiative, designed, prepared, and presented a mini-seminar on indexing to several other writers on the team. The participants all said they enjoyed it, they learned a lot, and they would be much better at indexing their manuals after the seminar. Other tasks included helping with the WebWorks template and modifying the FrameMaker template so that it worked better and so that it matched marketing’s visual design. This included creating a single master template to simplify the task of updating all manuals.

Comments

This project included many aspects of the usual software product development process: Rapidly changing products, short deadlines, software development continuing past document deadlines, shifting priorities, changing staff, and so on, all of which I took in stride, having had many years of experience with the software development environment..

Working with the EE staff was a pleasure. The engineers were informative and responsive, and my fellow writers and the manager of the publications group were competent, intelligent, and enjoyable people.

Tools

FrameMaker+SGML 6, Acrobat, PhotoShop, Outlook 2000, Microsoft Project, Windows 2000, Hummingbird Exceed (to access the server to run the product), SourceSafe, Excel, SnagIt, IXGen, Index Tools Professional, WebWorks Professional 6.

Senior Technical Writer, 04/1999 to 01/2001, BrightInfo/Annuncio Software

I started at BrightInfo, a start-up, which was later acquired by Annuncio, which chose to continue my contract due to the high praise BrightInfo engineers and management had for me. Annuncio was later purchased by PeopleSoft, which was later acquired by Oracle.

Responsibilities

Documented Internet eCommerce software. Starting with 40 HTML pages in late April 1999, I wrote a set of manuals (user’s guide, administration guide, integration guide, and template guide) in FrameMaker, totaling over 900 pages by product ship in late 2000. During the entire time I was working on this project, I was project lead, even after in-house writers were added to the project late in the cycle.

As project lead, I attended several weekly status and planning meetings; coordinated and ran documentation reviews; gave input to the GUI design (much of which was used); managed the documentation (document plans, scheduling, organization, and implementation); used the bug database to keep on top of problems and changes; used the software being documented and learned it in depth; wrote, edited, and indexed all manuals, taking screen shots and performing other usual writing tasks as needed; and wrote release notes. Also worked on several short-term documentation projects. I continued to be project lead until the end of the project in early 2001.

From April 1999, when the company was BrightInfo, to July 2000, after BrightInfo’s acquisition by Annuncio in March 2000, I was the sole writer on the project . In July 2000, the product was spun off into two additional products, requiring nearly triple the amount of documentation. At that time, I recommended the addition of another two writers to the project; that recommendation was followed with the addition of one in-house writer and one contractor. I continued to work on all three projects as project lead.

I designed and created the FrameMaker template for the books, creating a single master template that could be used for all the different types of files in a FrameMaker book, including the TOC and index. This template made it possible to update the styles and formats in a book in much less time than if there were different templates for each part of a book. I also created and used a custom WebWorks template to convert the documentation into Java/HTML help format.

I created some unique spreadsheets and modified my ongoing set of spreadsheet tools. I also created HTML pages to access several different sets of JavaDoc-created API documentation.

Comments

This project was fast-paced and fun. It included many of the usual challenges of a product being developed from the early stages to a mature, full-featured product. The product underwent several major design changes, which required my staying on top of the product and staying in good communication with other members of the team.

I was often complimented (a common comment: “You’re the best technical writer I have ever known”). I was also told that I had a better overall understanding of the product, since I had documented every aspect of it, than anyone else on the team.

I greatly enjoyed working with the development, QA, and product management staff. Everyone was competent, professional, quality-oriented, and a pleasure to work with.

Tools

FrameMaker 5.5 and 6, Acrobat, Outlook (including for scheduling meetings), Web browsers (for accessing and documenting the GUI portion of the product), HomeSite, Windows 98, SourceSafe, Excel, SnagIt, IXGen, WebWorks 2000 and later, WebWorks Professional 6.

Publications Manager, 06/1998 to 03/1999, Progress Software

I was working for a small branch of Progress Software that had been acquired before I started there. On a contract basis, I was hired as a Publications Manager, with the two goals of building a team and training a replacement who would work as a staff member.

Responsibilities

Built and managed a cross-country group of writers (three permanent, two contract) documenting a Java-based integrated development environment and application server for creating client- and server-side Java and HTML applications.

On my own initiative, I reviewed the release note process, which was quite time consuming and error prone. I came up with a revised process that made the release note process take a fraction of the time it had been previously taking and also made the release notes much more accurate. This revised process required some small but useful changes to the bug database and to the bug reporting process, which, after my presentation, were accepted as necessary changes and were implemented. These changes made it easier to create queries and pull bug reports.

I also hired several more writers, including a writer to work on the Java API documentation, as I oversaw the creation of the JavaDoc-generated documentation.

In addition to building a team and seeing a product through a major release, my tasks included mentoring a permanent employee so he could step into my shoes when my contract ended.

Along with the usual management tasks of attending planning meetings, writing document plans, managing the writing staff, coordinating efforts, interviewing candidates, putting out some fires in various areas, and numerous other tasks, my responsibilities also included:

Comments

The documentation side of this project went smoothly, especially after I implemented a writer’s style guide. This was my first full managerial position on a contract basis (all previous managerial experience was performed as a regular employee).

One challenge was that I stepped into a situation where there had been no publications manager before, and previous contract writers had used that fact to their advantage, taking over the project and not cooperating with permanent staff. This made the political situation delicate and combustible. Those same writers initially made it known that they did not like the fact that another contractor (and a woman at that) was being placed over them.

Faced with these obstacles, I was able to not only greatly improve the department’s relationships with other departments, but was also able to manage the recalcitrant and rebellious writers in such a way that they ended up thanking me for my fine leadership. One of them, who had initially objected to me in every possible way, said that I was the best manager he had ever worked for.

Tools

FrameMaker 5.5, Acrobat, RoboHelp, Outlook (including for scheduling meetings), Microsoft Project, HomeSite, Windows 98, UNIX, SourceSafe, Visio, Excel, SnagIt, IXGen, WebWorks.

Previous Projects

Previous projects have included:

I also