February 19, 2013

Taking the Pain Out of Writing with Defect Scribe

Helix ALM
Take the pain out of writingAs a technical writer, I write a variety of documents on any given day. I enjoy the variety of writing tasks that come with my job, for the most part, but writing defects is not something I like to spend a lot of time on. (Come on, who really likes writing defects?) So when I do stumble upon a product defect I need to share with our development team, instead of cursing to myself and pretending I didn’t see it, I can just let Defect Scribe explain the issue for me. The problem I have with writing defects is I’m not always sure if I’m including all the information our developers need to understand and fix the specific problem. When I use Defect Scribe to record the actions I performed to come across the issue, I don’t have to worry about keeping track of so many details. The results have everything I need to submit a thorough defect record in our TestTrack database. I just need to take a little time reviewing the results, adding any notes I feel might be helpful, and then I can create the defect right from Defect Scribe. But why stop at submitting defects? Here are a few other writing tasks I’ve found I can use Defect Scribe to accomplish. Author’s note: Some people think all tech writers do is write step-by-step instructions. Don’t be that guy. A Defect Scribe subscription can make writing steps easier, especially for people who don’t like to write, but it cannot replace your technical writing team.

Documenting product features

Let’s say I need to document a simple but important task, such as creating a code review in Surround SCM. This isn’t all that different than writing a defect, except the way I use the information Defect Scribe gives me is a little different. I tell Defect Scribe I want to record against Surround SCM. When the recording toolbar appears, I go ahead and create a new code review in Surround SCM.  Once the code review is created, I tell Defect Scribe to stop recording and a few seconds later, I have all the steps one needs to follow to create a code review at my disposal. [caption id="attachment_13031" align="alignnone" width="556"] Defect Scribe Results edited to documentation style[/caption] I simply edit the text for each step, keep the captured screenshots I could use in the documentation and remove the ones I don’t need, and save the updated information as a Word document. From there, I can copy them to my help authoring tool to apply the necessary formatting or even send them out for a tech or peer review before putting them in the help. [caption id="attachment_13032" align="alignnone" width="681"] Defect Scribe results exported to Microsoft Word format[/caption]

Double-checking my work

Even if I’ve already drafted a help topic for a new product feature, I can still use Defect Scribe to record the actions against the new feature and then double-check my draft against the results. This can come in handy when I need to ensure I don’t skip any details when I’m documenting a more complex task.

Emailing quick procedures to co-workers

Sometimes I’ve got some tips or shortcuts I can share with other tech writers on the team to make certain tasks easier. The easiest way for me to communicate these things is to send an email. I don’t always have a list of these tips just sitting around waiting to be emailed, but Defect Scribe can help me quickly compose one. After I’ve recorded the information I want to share, I can click the Send Email button and the steps are listed out in a new message for me.

Want to learn more?

Defect Scribe serves as a great “extra set of eyes”, which is quite the useful resource for all writers and non-writers alike.  And, the fact that it’s really easy to use is a no-brainer reason to give it a try. For more information about how Defect Scribe works, check out the Defect Scribe help.