A Failed Technical Documentation Project

Organizations and individuals talk about their success stories — it is important to talk about failures too.

Most often, we share our experiences that are derived from our successful projects. Many technical communicators use their blog space or community portals and groups to share their knowledge and expertise from successful projects such as how they planned CS help in Flare for a project, or integrated DITA in Drupal, or developed a prototype of a complex real estate system.

Although ‘we learn more from failures than from success’ is as well known, we generally tend to not to talk much about our failed projects.

Here, I take this opportunity to talk about a failed project, as one of my experiences in December 2012.

In November 2012, a business owner from East Coast New York approached me to develop functional specifications of their CRM. We agreed on the scope and I had to deliver a detailed functional specifications document, including wireframes. I did not realize that I should not work on this job as a technical communicator — it was a job for a business analyst with skills in IA or UX.

We discussed milestones, inputs and directions, and the collaborative process. I got the contract on 03 December and I needed to complete and deliver it by 22 Dec.

The proposed CRM was huge and was comparable to SalesForce or ZOHO (little smaller than these) and HighRise (little bigger than this). The client has been supportive, and responsive on emails, Skype and phone. I got a working template in WordPress (yes in WordPress) to write the details.

I said YES to this project because:

  • I had developed product documentation for a CRM  so I know about CRM systems.
  • I had used zohoCRM, BaseCamp, and GetHarvest (though all three at intermediate level). So, I know about the general workflow of a CRM. In addition, I was also working with an experienced SalesForce certified professional for some development project, so I could always seek his inputs if required (and I did eventually).
  • I am actively using JustInMind, and I knew I could do the wireframes.
  • I am familiar with using WP admin, so documentation environment was not an issue.
  • I analyzed at my work calendar and I had the time to work on it.
  • Client had wireframes ready for 1–2 modules so I had the base to develop documentation for other modules and complete it for the CRM.
  • And, so I committed myself to the job.

The deal was to follow the basic steps as:

  • Do some research on some CRM systems (Zoho, SalesForce, SugarCRM, Worketc and few more) and consolidate the best practices of these for preliminary notes (In hindsight now I realize that it was a wrong way to get started)
  • Start by planning for navigation; one menu for each module of CRM (again, this is not how projects specifications start)
  • Plan the UX for each module (Leads, Contacts, Accounts, Calendar, Messages, Settings, Events, and so on)
  • Write detailed notes on functional scope, use cases, do wireframes (in SwordSoft)
  • Get all these approved based on milestones (milestones based on modules’ documentation for UX and scope in MS Word, get it approved and migrate it to WP, and move to next module).

What exactly happened

  • I started research on Zoho, HighRise, and SalesForce and found it very different from my experience in CRM documentation. [So, my assumption that I had the experience to document CRMs was not correct.]
  • For all these reference CRMs, I realized that the whole workflow and UX *Leads — opportunity — account — contact* can be different and yet same. [I focused more to understand how these work and how these differ and less on what exactly we want out of these]
  • I had calls with client and explained my understanding and doubts. Somewhere and for some reason, I assumed a few things rather than clarifying. It doesn’t happen with me often though. The best part is that he gave me links to study and some YouTube video links too. I saw these useful sources and it gave me a false sense of guarantee, that I have understood it. I could not sense that I was not planning in right direction.
  • When I wrote the scope items, I started with working on wireframes, WITHOUT really freezing the LOAC workflow, and this is where I sensed that something wrong in what I was doing. Gradually, we both sensed uncertainty.
  • At this stage, I was asking such questions that I should have asked in week 1. But it was late now.
  • I got defensive. The deadline was approaching and I could not look back.

We had a call, and the project was shelved. Client was friendly, and asked me the reason of why it happened. It was a honest and transparent conversation. And we just smiled off.


By that time, I knew what differently I could do. (a) I could have sensed that working for realtysoft CRM technical documentation was a very different experience from what was required for this CRM specifications (b) I could have been little more focused while doing research on competitors

I also realized that “I should NOT say YES to a documentation project even if I have time, I know the domain, I know the documentation environment and even if the client is supportive. Not every can do project will be a success. The key to success does not change if I have time, experience, and technical skills; it is still planning and homework and an honest assessment of one’s skills and experience.

If it fails, it is perfectly fine to accept it, sign off amicably, and shake hands with the client.