Lessons from shifting perspectives: Technical Writing to Code Development of a simple utility for Flare and Blaze

Posted on March 15, 2009


Completed the first publicly available automatic batch script builder, tentatively titled Autotarbat ,:)  for Flare and Blaze.

Autotarbat Beta

What Autotarbat does for your mad single-sourcing publishing process

  • To start, provide a folder to all your Flare/Blaze projects. 
  • It generates a working batch file.
  • Copy it, edit/tweak it or or just run it.

It still has some known limitations which will be ironed out in coming releases. This should be helpful to give you a headstart rolling your own working versions right away.

Autotarbat was inspired from discussions on command-line build posts at the Madcap forums (http://forums.madcapsoftware.com)

This wasn’t as easy to finish. It was much more ambitious and technically complex than the PageLayout Resizer.

It was fun though, learning how to get the basics moving.

10 Lessons From Writing Your Own Tools:

  1. Recursive loop.
    WordPress has it in various forms and the WordPress Codex calls it the The Loop. I used a recursive loop to locate key files out of the thousand or so files being traversed, to ferret the ones we were interested in only namely the targets and projects.
  2. Useful short C# code tutorials can be found with Google – as learning assist tool.
    Short, tutorials are good. Long exposition – not so good.  
    Books in C# are useful. Just as important is using standard user interface components as you expect in standard Windows applications.
  3. Goal oriented learning works.
    How do I get a tool tip? How do I set text in a status bar? How do I do x and y?… 
    Its way easier to appreciate the ideas in an OOP (object oriented programming) paradigm when you actually have to apply it to a much larger problem and not merely to appreciate a theory/concept. It a stickier way of learning.
  4. See line by line execution – using breakpoints to debug loops.
    Like watching an orchestra.
    See live code executing line by line. See values assigned to variables, loops iterated. Time saver!
    In web development, all you get, are line execution error messages, after running.
  5. Anchoring and Panels – the secret to creating applications that work brilliantly on all display sizes from 4:3 screens to super 20 inch wide-screens.
    A bit similar to Capture v4’s new anchoring metaphor for callouts in a screenshot, but this one is immediately more dynamic and intuitive. Resize the windows all you want!
  6. Writing code and designing in a well designed IDE (VS 2005) is incredibly intuitive.
    Lots of nice touches to simplify debugging even before a single line of code is compiled. Its like automatic spell check for coders.
    Did i mention breakpoint debugging? First class!
  7. Attention to both big pictures and details are going are important.
    Workflow efficiencies come from selecting the right kind of defaults throughout the entire process. Its not just big pretty buttons.
  8. Never lose sight of what its meant to do and nothing more.
    Less is more.
    Less is more, is not necessarily easier when you’re in a coding and learning state of mind.
    Empathy. For Developers. For Users. For writers.
  9. Checklist boxes, strings and exception handling
    Usability comes from handling errors well – know your error and exception handling.
    Its a Collection of Items to be enumerated. You can never know too much about processing, parsing, replacing concatenating, splitting and all things strings handling.
  10. Appreciation for open extensible formats.
    Madcap Flare/Blaze’s (or even Madcap Capture) consistently adhere to open file format technologies like XML and standard off the shelf technology like SQL Server. This makes it easy for savvy, non-developers to build enhancements without a lot of work. There’s not a heavy community around this yet but its nice to be among the first to develop opportunities in this area, and to see what else it inspires. I am hoping it does.

The best practices and lessons in short and concise Web 2.0 usability books from Hoekmann help. A place to start for all things tech-coms and usability, including a review of Kurt Ament’s Single Sourcing book, is Scott DeLoach’s review section here.

Exhausted but satisfied.

Watching closely to see how many downloads AutoTarbat racks up on Codeplex stats in the coming weeks.

Should user assistance writers code? Should coders write? What do you think?

Posted in: Coding, Utilities